Todos os artigos

Front-end8 min de leitura

Angular Standalone Components: o que são e como migrar

O que são standalone components no Angular e como migrar um projeto com NgModule: o schematic oficial, as rotas com loadComponent, o bootstrapApplication e o inject().

Também em English, Español, Français

Se você trabalha com Angular há algum tempo, conhece o ritual: criou um componente, precisa declarar ele num NgModule, importar o módulo em outro módulo, exportar pra alguém usar... e quando algo não aparece na tela, a culpa quase sempre é de um módulo que faltou importar.

Os standalone components acabam com esse ritual. Cada componente diz sozinho do que precisa, e o NgModule deixa de ser obrigatório.

Publiquei a primeira versão deste post no Medium em 2023, e ele virou o meu texto mais lido por lá. Esta é a versão revisada: o código saiu dos prints e virou texto que dá pra copiar, corrigi dois erros que estavam no original e atualizei o que mudou no Angular desde então.

Os exemplos de migração vêm do angular-shop, o projeto de demonstração da Loiane Groner com as novidades do Angular.

TL;DR#

  • Standalone component é um componente que declara as próprias dependências no imports do @Component, sem precisar de um NgModule.
  • Desde o Angular 19 ele é o padrão: todo componente novo já nasce standalone. Pra um componente antigo continuar dependendo de módulo, ele precisa de standalone: false.
  • A migração é automática em três passos: ng generate @angular/core:standalone, rodado três vezes, uma pra cada modo, compilando entre um e outro.
  • As rotas você migra à mão: cada *-routing.module.ts vira um array Routes exportado, carregado com loadChildren ou, se for um componente só, com loadComponent.
  • O bootstrapApplication substitui o AppModule, e os providers viram funções: provideRouter, provideHttpClient.
  • O inject() não depende de standalone. Ele funciona em qualquer classe criada pela injeção de dependência e tem schematic próprio pra migrar.

O que é um standalone component#

Antes, um componente só existia dentro de um módulo. O módulo era quem dizia o que o componente podia usar:

// before: the module declares the component and imports what it needs
@NgModule({
  declarations: [CartComponent],
  imports: [CommonModule, RouterModule],
})
export class CartModule {}

Um standalone component traz essa lista dentro dele mesmo:

// after: the component imports its own dependencies
@Component({
  selector: 'app-cart',
  imports: [CurrencyPipe, RouterLink],
  templateUrl: './cart.component.html',
})
export class CartComponent {}

Repare que não tem standalone: true. Até o Angular 18 você precisava escrever essa linha. A partir do Angular 19, standalone é o padrão, e é o componente que ainda depende de módulo que precisa avisar, com standalone: false.

Com NgModule, o módulo decide o que o componente enxerga. Standalone, o componente decide sozinho

Na prática, isso muda três coisas:

  1. Fica claro do que o componente depende. Abriu o arquivo, a lista está ali, e não espalhada por módulos.
  2. O lazy loading fica mais fino. Dá pra carregar um componente sozinho numa rota, sem criar um módulo só pra isso.
  3. Menos arquivo pra manter. Some o cart.module.ts, some o cart-routing.module.ts.

E não precisa migrar tudo de uma vez: componentes standalone e módulos convivem no mesmo projeto. Um standalone pode ser importado num NgModule, e um módulo pode entrar no imports de um standalone.

Migrando com o schematic oficial#

O Angular tem um schematic que faz a maior parte do trabalho. Antes de rodar, o guia oficial pede três coisas:

  • o projeto estar no Angular 15.2 ou mais novo;
  • o projeto compilar sem erro;
  • estar numa branch limpa do Git, com tudo commitado. Assim, se a migração fizer bagunça, um git restore . desfaz.

O comando é um só:

ng generate @angular/core:standalone

Ele pergunta qual modo rodar. Rode os três, nessa ordem, compilando e testando o app entre um e outro:

  1. "Convert all components, directives and pipes to standalone": transforma cada componente, diretiva e pipe em standalone e preenche o imports de cada um com o que ele usa.
  2. "Remove unnecessary NgModule classes": apaga os módulos que ficaram vazios. O que ele não conseguir apagar sozinho, ele marca com um comentário TODO(standalone-migration) pra você resolver.
  3. "Bootstrap the application using standalone APIs": troca o bootstrapModule(AppModule) do main.ts pelo bootstrapApplication.
O mesmo comando, três vezes, um modo por vez. Compile entre cada um

Num projeto grande, dá pra ir por partes com a opção --path, migrando uma pasta de cada vez:

ng generate @angular/core:standalone --path src/app/cart

Depois dos três passos, o próprio guia sugere uma faxina:

  • procure os NgModule que sobraram e apague o que der à mão;
  • rode os testes unitários e corrija o que quebrou;
  • rode o formatador e o linter, porque o código gerado nem sempre segue o estilo do projeto.

Convertendo as rotas#

Depois do schematic, os módulos de funcionalidade (como o CartModule e o ProductsModule) muitas vezes continuam existindo, só pra carregar as rotas. Essa parte o schematic de standalone não faz, então é com você. A boa notícia: é a parte mais simples.

O módulo de rotas vira um array#

Antes, cada funcionalidade tinha um módulo só pra registrar as rotas:

// cart-routing.module.ts (before)
import { NgModule } from '@angular/core'
import { RouterModule, Routes } from '@angular/router'
import { CartComponent } from './cart/cart.component'
 
const routes: Routes = [{ path: '', component: CartComponent }]
 
@NgModule({
  imports: [RouterModule.forChild(routes)],
  exports: [RouterModule],
})
export class CartRoutingModule {}

Depois, é só o array, exportado:

// cart.routes.ts (after)
import { Routes } from '@angular/router'
import { CartComponent } from './cart/cart.component'
 
export const CART_ROUTES: Routes = [{ path: '', component: CartComponent }]

O mesmo pra produtos:

// products.routes.ts (after)
import { Routes } from '@angular/router'
import { ProductFormComponent } from './product-form/product-form.component'
import { ProductsListComponent } from './products-list/products-list.component'
 
export const PRODUCTS_ROUTES: Routes = [
  { path: '', component: ProductsListComponent },
  { path: 'new', component: ProductFormComponent },
]

Na primeira versão deste post, o products.routes.ts exportava CART_ROUTES (copiei do arquivo do carrinho e esqueci de trocar), enquanto as rotas principais importavam outro nome. Do jeito que estava, o código nem compilava. Aqui o nome é um só: PRODUCTS_ROUTES.

As rotas principais apontam pros arrays#

No app-routing.module.ts, o loadChildren carregava um módulo:

// app-routing.module.ts (before)
const routes: Routes = [
  { path: '', pathMatch: 'full', redirectTo: 'products' },
  {
    path: 'products',
    loadChildren: () => import('./products/products.module').then((m) => m.ProductsModule),
  },
  {
    path: 'cart',
    loadChildren: () => import('./cart/cart.module').then((m) => m.CartModule),
  },
]
 
@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule],
})
export class AppRoutingModule {}

Agora ele carrega o array de rotas. O lazy loading continua igual: o código de produtos só é baixado quando alguém entra em /products.

// app.routes.ts (after)
import { Routes } from '@angular/router'
 
export const APP_ROUTES: Routes = [
  { path: '', pathMatch: 'full', redirectTo: 'products' },
  {
    path: 'products',
    loadChildren: () => import('./products/products.routes').then((m) => m.PRODUCTS_ROUTES),
  },
  {
    path: 'cart',
    loadChildren: () => import('./cart/cart.routes').then((m) => m.CART_ROUTES),
  },
]

Uma rota, um componente: loadComponent#

O carrinho tem uma rota só. Não precisa de um arquivo de rotas pra ele: com loadComponent, a rota carrega o componente direto, e o cart.routes.ts pode ser apagado.

// app.routes.ts
{
  path: 'cart',
  loadComponent: () => import('./cart/cart/cart.component').then((m) => m.CartComponent),
}

E se o arquivo usar export default, nem o .then é necessário:

// cart.component.ts: export default class CartComponent {}
{
  path: 'cart',
  loadComponent: () => import('./cart/cart/cart.component'),
}

O loadChildren aceita o mesmo atalho quando o arquivo de rotas tem export default.

Tem rota carregando componente direto, sem lazy loading, e quer mudar todas de uma vez? Existe outro schematic pra isso: ng generate @angular/core:route-lazy-loading troca o component por loadComponent nas rotas que ele encontrar.

O main.ts sem AppModule#

O terceiro passo do schematic já troca o bootstrap pra bootstrapApplication. Mas, se o projeto tinha um AppRoutingModule, ele costuma entrar no importProvidersFrom, ainda como módulo:

// main.ts (before)
bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(BrowserModule, AppRoutingModule),
    provideHttpClient(withInterceptorsFromDi()),
  ],
})

Troque o módulo de rotas pelo provideRouter, com o array:

// main.ts (after)
import { bootstrapApplication } from '@angular/platform-browser'
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http'
import { provideRouter } from '@angular/router'
import { AppComponent } from './app/app.component'
import { APP_ROUTES } from './app/app.routes'
 
bootstrapApplication(AppComponent, {
  providers: [provideRouter(APP_ROUTES), provideHttpClient(withInterceptorsFromDi())],
})

O BrowserModule também pode sair: o bootstrapApplication já traz o que ele fazia. Com isso, dá pra apagar com segurança:

  • app-routing.module.ts, cart-routing.module.ts e products-routing.module.ts;
  • cart.module.ts e products.module.ts, se o schematic ainda não tiver apagado.

A função inject()#

No original eu apresentei o inject() como uma "nova opção com standalone components". Ele não tem nada a ver com standalone. Desde o Angular 14, o inject() funciona em qualquer classe que a injeção de dependência cria (componente, diretiva, pipe, serviço), com ou sem módulo. Ele só apareceu junto porque os dois chegaram mais ou menos na mesma época.

O que ele faz: busca uma dependência no injetor ativo, sem precisar do construtor.

// constructor injection
export class ProductsListComponent {
  constructor(
    private service: ProductsService,
    private cartService: CartService,
  ) {}
}
 
// with inject()
export class ProductsListComponent {
  private service = inject(ProductsService)
  private cartService = inject(CartService)
}

Por que preferir? O código fica mais curto, os tipos ficam mais precisos (segundo a própria documentação, ele também combina melhor com os decorators padrão do JavaScript), e ele também funciona em funções, como um guard de rota funcional. A única regra é chamar o inject() num contexto de injeção: no construtor, na inicialização de um campo da classe ou numa função que o Angular chama nesse contexto (como guards e resolvers). Num setTimeout ou num clique, ele dá erro.

E tem schematic pra converter tudo:

ng generate @angular/core:inject

Conclusão#

Standalone components deixam cada componente responsável pelas próprias dependências, e isso deixa o projeto mais fácil de ler, de dividir e de carregar aos pouquinhos. Com o schematic, a parte chata da migração é automática. O que sobra pra você são as rotas e o main.ts, e é pouca coisa.

Se o seu projeto ainda está cheio de NgModule, o caminho é: branch limpa, os três modos do schematic com build entre eles, rotas à mão e depois o ng generate @angular/core:inject pra fechar.

Referências#

Atualizado em

  • Front-end
  • angular
  • standalone
  • typescript
  • migração
  • lazy loading

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.