Tous les articles

Front-end8 min de lecture

Angular Standalone Components : définition et migration

Ce que sont les standalone components d'Angular et comment migrer depuis NgModule : schematic officiel, routes avec loadComponent, bootstrapApplication et inject().

Aussi en Português, English, Español

Si tu travailles avec Angular depuis un moment, tu connais le rituel : tu as créé un composant, tu dois le déclarer dans un NgModule, importer le module dans un autre module, l'exporter pour que quelqu'un puisse s'en servir... et quand quelque chose n'apparaît pas à l'écran, le coupable est presque toujours un module que tu as oublié d'importer.

Les standalone components mettent fin à ce rituel. Chaque composant dit lui-même ce dont il a besoin, et le NgModule n'est plus obligatoire.

J'ai publié la première version de cet article sur Medium en 2023, en portugais, et c'est devenu mon texte le plus lu là-bas. Voici la version revue : le code est sorti des captures d'écran pour devenir du texte que tu peux copier, j'ai corrigé deux erreurs qui étaient dans l'original et j'ai mis à jour ce qui a changé dans Angular depuis.

Les exemples de migration viennent d'angular-shop, le projet de démonstration de Loiane Groner avec les nouveautés d'Angular.

TL;DR#

  • Un standalone component est un composant qui déclare ses propres dépendances dans le imports du @Component, sans avoir besoin d'un NgModule.
  • Depuis Angular 19, c'est le comportement par défaut : tout nouveau composant naît standalone. Pour qu'un ancien composant continue de dépendre d'un module, il lui faut standalone: false.
  • La migration est automatique, en trois étapes : ng generate @angular/core:standalone, lancé trois fois, une pour chaque mode, en compilant entre chaque passage.
  • Les routes, tu les migres à la main : chaque *-routing.module.ts devient un tableau Routes exporté, chargé avec loadChildren ou, s'il s'agit d'un seul composant, avec loadComponent.
  • bootstrapApplication remplace l'AppModule, et les providers deviennent des fonctions : provideRouter, provideHttpClient.
  • inject() ne dépend pas de standalone. Il fonctionne dans n'importe quelle classe créée par l'injection de dépendances et a son propre schematic pour la migration.

Ce qu'est un standalone component#

Avant, un composant n'existait qu'à l'intérieur d'un module. C'était le module qui disait ce que le composant pouvait utiliser :

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

Un standalone component porte cette liste en lui-même :

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

Remarque qu'il n'y a pas de standalone: true. Jusqu'à Angular 18, tu devais écrire cette ligne. À partir d'Angular 19, standalone est le comportement par défaut, et c'est le composant qui dépend encore d'un module qui doit le signaler, avec standalone: false.

Avec NgModule, le module décide de ce que voit le composant. En standalone, le composant décide seul

En pratique, ça change trois choses :

  1. On voit clairement de quoi dépend le composant. Tu ouvres le fichier, la liste est là, au lieu d'être éparpillée entre les modules.
  2. Le lazy loading devient plus fin. Tu peux charger un seul composant sur une route, sans créer un module rien que pour ça.
  3. Moins de fichiers à maintenir. Le cart.module.ts disparaît, le cart-routing.module.ts aussi.

Et pas besoin de tout migrer d'un coup : composants standalone et modules cohabitent dans le même projet. Un standalone peut être importé dans un NgModule, et un module peut entrer dans le imports d'un standalone.

Migrer avec le schematic officiel#

Angular a un schematic qui fait la plus grande partie du travail. Avant de le lancer, le guide officiel demande trois choses :

  • que le projet soit en Angular 15.2 ou plus récent ;
  • que le projet compile sans erreur ;
  • être sur une branche Git propre, avec tout commité. Comme ça, si la migration met le bazar, un git restore . annule tout.

Il n'y a qu'une commande :

ng generate @angular/core:standalone

Elle te demande quel mode lancer. Lance les trois, dans cet ordre, en compilant et en testant l'app entre chaque :

  1. "Convert all components, directives and pipes to standalone" : transforme chaque composant, directive et pipe en standalone et remplit le imports de chacun avec ce qu'il utilise.
  2. "Remove unnecessary NgModule classes" : supprime les modules qui sont restés vides. Ce qu'il n'arrive pas à supprimer tout seul, il le marque avec un commentaire TODO(standalone-migration) pour que tu t'en occupes.
  3. "Bootstrap the application using standalone APIs" : remplace le bootstrapModule(AppModule) du main.ts par bootstrapApplication.
La même commande, trois fois, un mode à la fois. Compile entre chaque

Sur un gros projet, tu peux avancer par morceaux avec l'option --path, en migrant un dossier à la fois :

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

Après les trois étapes, le guide lui-même suggère un petit ménage :

  • cherche les NgModule qui restent et supprime à la main ce que tu peux ;
  • lance les tests unitaires et corrige ce qui a cassé ;
  • lance le formateur et le linter, parce que le code généré ne suit pas toujours le style du projet.

Convertir les routes#

Après le schematic, les modules de fonctionnalité (comme le CartModule et le ProductsModule) existent souvent encore, juste pour charger les routes. Cette partie, le schematic standalone ne la fait pas, donc c'est à toi de jouer. La bonne nouvelle : c'est la partie la plus simple.

Le module de routes devient un tableau#

Avant, chaque fonctionnalité avait un module rien que pour enregistrer ses routes :

// 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 {}

Après, c'est juste le tableau, exporté :

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

Pareil pour les produits :

// 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 },
]

Dans la première version de cet article, le products.routes.ts exportait CART_ROUTES (je l'avais copié du fichier du panier et j'avais oublié de changer le nom), alors que les routes principales importaient un autre nom. Tel quel, le code ne compilait même pas. Ici, il n'y a qu'un seul nom : PRODUCTS_ROUTES.

Les routes principales pointent vers les tableaux#

Dans le app-routing.module.ts, le loadChildren chargeait un module :

// 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 {}

Maintenant, il charge le tableau de routes. Le lazy loading reste le même : le code des produits n'est téléchargé que quand quelqu'un va sur /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),
  },
]

Une route, un composant : loadComponent#

Le panier n'a qu'une route. Pas besoin d'un fichier de routes pour lui : avec loadComponent, la route charge directement le composant, et le cart.routes.ts peut être supprimé.

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

Et si le fichier utilise export default, même le .then n'est plus nécessaire :

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

Le loadChildren accepte le même raccourci quand le fichier de routes a un export default.

Tu as des routes qui chargent des composants directement, sans lazy loading, et tu veux toutes les changer d'un coup ? Il existe un autre schematic pour ça : ng generate @angular/core:route-lazy-loading remplace le component par loadComponent dans les routes qu'il trouve.

Le main.ts sans AppModule#

La troisième étape du schematic passe déjà le bootstrap à bootstrapApplication. Mais si le projet avait un AppRoutingModule, il finit en général dans le importProvidersFrom, toujours sous forme de module :

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

Remplace le module de routes par provideRouter, avec le tableau :

// 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())],
})

Le BrowserModule peut partir aussi : bootstrapApplication apporte déjà ce qu'il faisait. Avec ça, tu peux supprimer sans risque :

  • app-routing.module.ts, cart-routing.module.ts et products-routing.module.ts ;
  • cart.module.ts et products.module.ts, si le schematic ne les a pas encore supprimés.

La fonction inject()#

Dans l'original, j'ai présenté inject() comme une « nouvelle option avec les standalone components ». Il n'a rien à voir avec standalone. Depuis Angular 14, inject() fonctionne dans n'importe quelle classe que l'injection de dépendances crée (composant, directive, pipe, service), avec ou sans module. Il est juste arrivé en même temps, parce que les deux sont sortis à peu près à la même époque.

Ce qu'il fait : il récupère une dépendance dans l'injecteur actif, sans passer par le constructeur.

// 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)
}

Pourquoi le préférer ? Le code est plus court, les types sont plus précis (selon la documentation elle-même, il s'accorde aussi mieux avec les decorators standard de JavaScript), et il fonctionne aussi dans des fonctions, comme un guard de route fonctionnel. La seule règle, c'est d'appeler inject() dans un contexte d'injection : dans le constructeur, à l'initialisation d'un champ de la classe ou dans une fonction qu'Angular appelle dans ce contexte (comme les guards et les resolvers). Dans un setTimeout ou dans un clic, il lève une erreur.

Et il y a un schematic pour tout convertir :

ng generate @angular/core:inject

Conclusion#

Les standalone components rendent chaque composant responsable de ses propres dépendances, et ça rend le projet plus facile à lire, à découper et à charger petit à petit. Avec le schematic, la partie pénible de la migration est automatique. Ce qui te reste, ce sont les routes et le main.ts, et ce n'est pas grand-chose.

Si ton projet est encore plein de NgModule, le chemin est : branche propre, les trois modes du schematic avec un build entre chaque, les routes à la main, puis ng generate @angular/core:inject pour boucler.

Références#

  • Front-end
  • angular
  • standalone
  • typescript
  • migration
  • lazy loading

Écrit par

Ingénieure logiciel et designer. J'écris sur ce que je rencontre en créant des apps, des APIs et des produits.