Angular CLI en 5 min

Cet article fait partie de la série d’articles Angular from Scratch.

Le CLI Angular (i.e. Command Line Interface) permet de faciliter l’exécution de nombreuses tâches sur un projet Angular. Il n’est, cependant, pas facile de se rappeler de toutes les commandes. Cet article a pour but d’expliciter quelques-unes des commandes principales et de leurs options.

@meteorphoto

La doc complête du CLI Angular se trouve sur les pages suivantes:

Avant d’installer le CLI Angular avec NPM, il faut installer, au préalable, Node.js: installation de Node.js.

L’installation du CLI est ensuite directe:

npm install @angular/cli 

Certaines options sont communes à plusieurs commandes, par exemple:

Commande Commentaires
Afficher l’aide générale
ng –h 
ng help
Afficher l’aide d’une commande
ng <commande> --help 
ng <alias de la commande> --help 
ng <commande> <option> --help 
ng <alias de la commande> <alias option> --help
Simuler l’exécution
ng <commande> <options> --dry-run 
ng <commande> <options> -d 
Aucune modification des fichiers existants ne sera effectuée
Forcer la génération de fichiers en écrasant ceux existants
ng <commande> <options> --force 
ng <commande> <options> -f

Les options peuvent être indiquées de différentes façons:

  • Sans indiquer de valeur pour l’option: c’est la valeur par défaut de l’option qui sera utilisée.
  • En indiquant explicitement une valeur.

Voici quelques-unes des syntaxes possibles pour préciser un option:

Commande Exemple
Si la valeur attendue de l’option est un booléen
ng <commande> --<nom option> 

La valeur de l’option sera l’opposé de la valeur par défaut.

ng new <nom application> --skip-tests 

Les fichiers de tests ne seront pas générés (par défaut, les fichiers de test sont générés).

Préciser la valeur de l’option explicitement
ng <commande> --<nom option> <valeur option> 
ng <commande> --<nom option>=<valeur option>
ng new <nom application> --skip-tests true 
ng new <nom application> --skip-tests=true
Utiliser directement des alias
ng <commande> --<alias option> <valeur option> 
ng <commande> --<alias option>=<valeur option> 
ng new <nom application> --S true 
ng new <nom application> --S=true 
Utiliser des options sans tirets avec des majuscules Par exemple, les options suivantes sont équivalentes:

--skip-tests
--skipTests

Créer une nouvelle application (ng new)

La commande est:

ng new <nom application> <options> 
ng n <nom application> <options> 

Quelques options courantes:

Commande Commentaires
Créer une nouvelle application
ng new <nom application> 
ng n <nom application>
Eviter la génération des fichiers de test *.spec.ts
ng new <nom application> --skip-tests 
ng new <nom application> -S
Eviter l'installation des packages NPM
ng new <nom application> --skip-install
npm install ne sera pas exécuté après création des fichiers de l'application
Installer un module de routing
ng new <nom application> --routing
Rajoute le fichier src/app/app-routing.module.ts.
Générer dans un répertoire
ng new <nom application> --directory <chemin répertoire>
Préciser l'extension des fichiers de style
ng new <nom application> --style <extension> 
Les valeurs possibles sont: "css", "scss", "less", "styl".

Les fichiers suivants seront générés:

  • src/styles.<extension>
  • src/app/app.component.<extension>

L'indication de l'extension peut aussi être indiquée dans le fichier angular.json en utilisant le paramètre "styleext".

Inclure le style dans le fichier du composant
ng new <nom application> --inline-style 
ng new <nom application> -s 
Le style est inclus dans les fichiers <nom composant>.component.ts.
Indiquer la valeur préfixant les sélecteurs
ng new <nom application> --prefix <nom préfixe> 
ng new <nom application> -p <nom préfixe>
Le préfixe des sélecteurs sera utilisé dans les composants:

@component({ 
    selector: '<nom préfixe>-root', 
    templateUrl: './app.component.html', 
    styleUrls: ['./app.component.css'] 
}) 

Le préfixe peut être modifié dans le fichier angular.json au niveau du paramètre "prefix".

Créer un workspace vide sans projet
ng new <nom application> --create-application false 
Le répertoire src et son contenu ne seront pas générés.

Générer un nouvel élément (ng generate)

La commande est:

ng generate <type élément> <options> 
ng g <type élément> <options> 

Un élément peut être généré dans un répertoire spécifique en rajoutant le chemin de ce répertoire devant le nom de l'élement, par exemple:

ng generate component repertoire1/repertoire2/<nom composant>

Dans ce cas, si le répertoire repertoire1/repertoire2 n'existe pas, il sera créé.

Quelques exemples des options possibles:

Commande Options Commentaire

Composant

ng g component  
ng g c
--help
Affiche toutes les options
ng g component <nom composant> 
ng g c <nom composant>
--flat
Le composant sera créé directement dans le répertoire src/app
(pas de répertoire pour le composant).
--inline-template
-t
Le template sera inclus dans le fichier du composant
(<nom composant>.component.ts).
--inline-style
-s
Le style sera inclus dans le fichier du composant.
--spec
Si la valeur est false, le fichier .spec pour les tests ne sera pas généré.

La valeur par défaut est true.
--module <nom  module> 
-m <nom module>
Précise le cas échéant le module dans lequel le composant sera créé.
--project <nom projet> 
-p <nom projet> 
Précise le cas échéant le projet dans lequel le composant sera créé.
--view-encapsulation <nom strategie> 
-v <nom stratégie>
Indique la stratégie d'encapsulation de la vue à utiliser.
--change-detection <nom stratégie> 
-c <nom stratégie>
Indique la stratégie de détection de la vue à utiliser.

Application

ng g application <nom appli.> 
ng g app <nom appli.> 
Permet de créer une application dans le répertoire "projects"
du workspace.

Le nom du répertoire "projects" peut être modifié
avec le paramètre newProjectRoot dans le fichier angular.json:

{ 
  "$schema": "./node_modules/@angular/
cli/lib/config/schema.json", 
  "version": 1, 
  "newProjectRoot": "projects",
  "projects": { }, 
} 
ng g application 
ng g app
--help
Affiche toutes les options
ng g application <nom appli.> 
ng g app <nom appli>
--routing
Permet de rajouter un module de routing. Le fichier créé sera
projects/<nom application>/src/app/app-routing.module.ts.

Le RouterModule sera importé dans le module de routing avec
RouterModule.forChild():

@NgModule({ 
    imports: [RouterModule.forChild([])], 
    // ...
}) 
--skip-install
npm install ne sera pas exécuté après création de l'application.
--skip-package-json
Ne rajoute pas les dépendances dans le fichier package.json.

Bibliothèque

ng g library <nom lib.> 
ng g lib <nom lib.> 
Permet de créer une bibliothèque générique dans le répertoire
"projects/<nom lib.>" du workspace.

Le nom du répertoire "projects" peut être modifié avec le paramètre
newProjectRoot dans le fichier angular.json:

{ 
  "$schema": "./node_modules/@angular/
cli/lib/config/schema.json", 
  "version": 1, 
  "newProjectRoot": "projects", 
  "projects": { }, 
} 

Le point d'entrée de la bibliothèque est
projects/<nom lib.>/src/public-api.ts. Tous les
composants, modules et services implémentés dans la bibliothèque sont exportés dans ce fichier.

La bibliothèque est un cas particulier de projet, il est donc indiqué
dans le fichier angular.json:

{ 
  "$schema": "./node_modules/@angular/
cli/lib/config/schema.json", 
  "version": 1, 
  "newProjectRoot": "projects", 
  "projects": { 
    "mylibrary": { 
      "projectType": "library", 
      "root": "projects/mylibrary", 
      "sourceRoot": "projects/mylibrary/src", 
      ... 
    }}, 
} 

Le fichier tsconfig.json est modifié car les chemins vers la bibliothèque sont rajoutés:

{ 
  "compileOnSave": false, 
  "compilerOptions": { 
    ... 
    "paths": { 
      "mylibrary": [ 
        "dist/mylibrary" 
      ], 
      "mylibrary/*": [ 
        "dist/mylibrary/*" 
      ] 
    } 
  }, 
  ... 
  } 
} 
ng g library  
ng g lib
--help
Affiche toutes les options
ng g library <nom lib.> 
ng g lib <nom lib.>
--entry-file <chemin du fichier> 
Précise le point d'entrée de la bibliothèque.
--skip-ts-config
Ne pas mettre à jour le fichier tsconfig.json pour rajouter les chemins de la bibliothèque.

Module

ng g module <nom module> 
ng g m <nom module> 
Crée un feature module dans le répertoire src/app/<nom module>
ng g module  
ng g m
--help
Affiche toutes les options
ng g module <nom module> 
ng g m <nom module> 
--project <nom project>
Précise le cas échéant, le projet dans lequel le feature module sera créé.
--flat
Crée le feature module directement dans le répertoire src/app.
--module <nom module> 
-m <nom module>
Précise le nom du module dans lequel le feature module à créer sera déclaré.
--routing
Permet de rajouter un module de routing pour le feature module à créer.
Le fichier de ce module sera nommé <nom du module>.module.ts.

Le RouterModule sera importé dans le module de routing avec
RouterModule.forChild():

@NgModule({ 
    imports: [RouterModule.forChild([])], 
    // ...
}) 

Service

ng g service <nom service> 
ng g s <nom service>
Crée un service directement dans le répertoire app/src.
ng g service  
ng g s
--help
Affiche toutes les options.
ng g service <nom service> 
ng g s <nom service> 
--project <nom projet>
Précise le cas échéant, le projet dans lequel le service sera créé.
--spec false 
--skip-tests 
Permet d'empêcher la création d'un fichier de test
src/app/<nom service>.spec.ts

Classe

ng g class <nom classe> 
ng g cl <nom classe>
Crée une classe directement dans le répertoire app/src.
ng g class  
ng g cl
--help
Affiche toutes les options.
ng g class <nom classe> 
ng g cl <nom classe>
--project <nom projet>
Précise le cas échéant, le projet dans lequel la classe sera créée.
--spec false 
--skip-tests 
Permet d'empêcher la création d'un fichier de test
src/app/<nom service>.spec.ts
--type <valeur type>
Permet d'indiquer le nom d'un type qui sera utilisé dans le nom
du fichier de la classe <nom classe>.<nom type>.ts.

Interface

ng g interface <nom interface> 
ng g i <nom interface> 
Crée une interface dans le répertoire src/app.
ng g interface 
ng g i
--help
Affiche toutes les options.
ng g interface <nom interface> 
ng g i <nom interface> 
--project <nom projet>
Précise le cas échéant, le projet dans lequel l'interface sera créée.

Enum

ng g enum <nom enum> 
ng g e <nom enum> 
Crée un enum dans le répertoire src/app.
ng g enum  
ng g e 
--help
Affiche toutes les options.
ng g enum <nom enum> 
ng g e <nom enum> 
--project <nom projet>
Précise le cas échéant, le projet dans lequel l'enum sera créé.

Guard

ng g guard <nom guard> 
ng g g <nom guard>
Crée un guard dans le répertoire src/app.
ng g guard  
ng g g
--help
Affiche toutes les options.
ng g guard <nom guard> 
ng g g <nom guard>
--implements <nom interface> 
Précise le cas échéant, le nom de l'interface que doit implémenter
le guard.
--project <nom projet>
Précise le cas échéant, le projet dans lequel le guard sera créé.

Pipe

ng g pipe <nom pipe> 
ng g p <nom pipe> 
Crée un pipe dans le répertoire src/app et le rajoute dans le
module de l'application.
ng g pipe  
ng g p 
--help
Affiche toutes les options.
ng g pipe <nom pipe> 
ng g p <nom pipe> 
--project <nom projet>
Précise le cas échéant, le projet dans lequel le pipe sera créé.
--module <nom module> 
-m <nom module> 
Précise le cas échéant le module dans lequel le pipe sera déclaré.
Par défaut, c'est src/app/app.module.ts.
--skip-import
Permet d'éviter d'importer le pipe dans le module par défaut
c'est-à-dire src/app/app.module.ts.
--spec false 
--skip-tests 
Permet d'empêcher la création d'un fichier de test
src/app/<nom pipe>.pipe.spec.ts.
Comment consommer une bibliothèque ?

Il faut construire la bibliothèque avant de construire l'application qui la consomme:

ng build <nom bibliothèque> 

Après création de la bibliothèque, étant donné que son chemin est indiqué dans le fichier tsconfig.json avec la configuration:

{ 
  "compileOnSave": false, 
  "compilerOptions": { 
    ... 
    "paths": { 
      "mylibrary": [ 
        "dist/mylibrary" 
      ], 
      "mylibrary/*": [ 
        "dist/mylibrary/*" 
      ] 
    } 
  }, 
  ... 
  } 
} 

Il suffit d'importer directement un élément de la bibliothèque:

import { <nom élément à importer> } from 'mylibrary'; 

Effectuer une build (ng build)

La commande est (à exécuter dans le répertoire du workspace):

ng build <options> 
ng b <options> 

On peut effectuer une build pour un projet spécifique en exécutant:

ng build <nom du projet> <options> 
ng b <nom du projet> <options> 

Le répertoire de sortie peut être modifié dans le fichier angular.json avec le paramètre "outputPath". Par défaut, le répertoire est dist/<nom du workspace> .

La compilation va générer les fichiers:

  • runtime.js contenant le runtime WebPack.
  • main.js contenant le code de l'application.
  • polyfills.js contenant les platform polyfills.
  • style.js contenant les styles.
  • vendor.js contenant les fichiers angular.

Ces fichiers sont référencés par le fichier index.html généré.

Options Commentaires
Pour effectuer la build avec les paramètres de production Ces syntaxes sont équivalentes:

--prod 
--configuration=production 
--configuration production 
--c=production 
--c production 
--prod=true 
--prod true
Par défaut cette configuration est présente dans le fichier angular.json.
Pour lancer une compilation avec une configuration personnalisée Ces syntaxes sont équivalentes:

--configuration <nom configuration> 
--configuration=<nom configuration> 
--c <nom configuration> 
--c=<nom configuration>
Il faut rajouter la configuration personnalisée dans le fichier angular.json dans la liste "configurations" sous la liste "builds".
Pour builder dans un répertoire spécifique
--output-path <chemin du répertoire>
Pour générer une carte des sources
--source-map
Pour compiler "Ahead Of Time"
--aot
Il s'agit d'une optimisation pour réduire le temps de compilation du code Javascript par le browser au moment de son chargement.
Pour compiler et s'abonner aux changements des fichiers sources
--watch
En cas de modifictions des fichiers source, le code est recompilé.
Pour indiquer explicitement un point d'entrée de l'application
--index <nom du fichier>
Par défaut, le point d'entrée est index.html.
Augmenter la verbosité
--verbose
Utiliser un fichier tsconfig.json spécifique
--ts-config <chemin du fichier>

Quand on utilise la configuration de production, par défaut, les options importantes de compilation sont (indiquées dans le fichier angular.json):

"configurations": { 
            "production": { 
              "fileReplacements": [ 
                { 
                  "replace": "src/environments/environment.ts", 
                  "with": "src/environments/environment.prod.ts" 
                } 
              ], 
              "optimization": true, 
              "outputHashing": "all", 
              "sourceMap": false, 
              "extractCss": true, 
              "namedChunks": false, 
              "aot": true, 
              "extractLicenses": true, 
              "vendorChunk": false, 
              "buildOptimizer": true, 
            }, 

Parmi ces options:

  • "optimization" permet d'appliquer des optimisations sur la build générée.
  • "outputHashing": permet de générer un bundle avec des noms de fichier comportant une clé de hashage du fichier. Cette clé de hashage rend le nom du fichier différent si le fichier est différent entre 2 versions. Les noms différents permettent d'éviter au browser d'utiliser une version antérieure du fichier récupérée à partir de son cache.

    Pour désactiver cet élément, on peut lancer une build avec l'option:

    ng build --output-hashing=none 
    
  • "aot" (i.e. ahead of time): le code Javascript généré est compilé au moment du build de façon à optimiser son chargement par le browser.
  • "vendorChunk" permet de ne pas utiliser un bundle séparé pour le code des dépendances.
  • "buildOptimizer": des optimisations sont appliquées au moment de la compilation et tout le code et ses dépendances externes se trouvent dans un bundle unique.

    Cette option applique un "tree-shaking" sur le code JS généré c'est-à-dire que le bundle résultant ne contient pas tout le code des dépendances. Il contient seulement le code des dépendances qui est réellement utilisé.

Lancer un service web de développement (ng serve)

La commande est (à exécuter dans le répertoire du workspace):

ng serve <options> 
ng s <options> 

Avant de lancer un service web pour exécuter l'application, une build est effectuée.

Options Commentaires
Pour lancer un browser au moment d'exécuter l'application
--open 
-o
Le browser par défaut est ouvert.
Lancer l'exécution sur un port spécifique
--port <numéro du port>
Le port par défaut est 4200.
Recharger la page si le code est modifié
--live-reload
Lancer le service web en utilisant HTTP
--ssl
Recompile en cas de changement du code
--watch 

Exécuter une target (ng run)

Les targets sont définies pour chaque projet dans le fichier angular.json au niveau du paramètre "architect" d'un projet.

Par exemple:

{ 
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json", 
  "version": 1, 
  "newProjectRoot": "projects", 
  "projects": { 
    "mynewapplication": { 
      "projectType": "application", 
      "schematics": {}, 
      "root": "", 
      "sourceRoot": "src", 
      "prefix": "app", 
      "architect": { 
        "build": {}, 
        "serve": {}, 
        "extract-i18n": {}, 
        "test": {}, 
        "lint": {}, 
        "e2e": {} 
      } 
    } 
  }, 
  "defaultProject": "mynewapplication" 
} 

On peut lancer l'exécution d'une target en exécutant:

ng run <nom projet>:<nom de la target> 

Par exemple dans l'exemple précédent pour exécuter la target "build" du projet "mynewapplication":

ng run mynewapplication:build 

On peut préciser une configuration:

ng run <nom projet>:<nom de la target> --configuration <nom configuration> 
ng run <nom projet>:<nom de la target> -c <nom configuration> 

Exécuter les tests (ng test et ng e2e)

Exécuter les tests unitaires

Les tests unitaires peuvent être exécutés en lançant la commande:

ng test <options> 
ng t <options> 

Ces tests se trouvent au niveau de chaque composants dans des fichiers nommés <nom du composant>.spec.ts

Les tests peuvent être lancés pour un projet spécifique en exécutant:

ng test <nom du projet> <options> 
ng t <nom du projet> <options> 

Les tests sont exécutés par un outil appelé karma. Cet outil indique le résultat des tests sur un browser à l'adresse par défaut localhost:9876 (le port est paramétrable dans karma.conf.js).

Options Commentaires
Pour générer un rapport contenant la converture de test
--code-coverage
Le résultat est généré dans un répertoire nommé /coverage.

On peut indiquer un répertoire particulier dans le fichier karma.conf.js:

coverageIstanbulReporter: { 
      dir: require('path').join(__dirname, './coverage/<nom application>'), 
      ... 
    },
Pour indiquer la progression sur la console lors de l'exécution
--progress
Pour exécuter les tests une seule fois
--watch false
Comment débugguer un test unitaire ?
  1. Exécuter le test avec ng test
  2. Quand la page de karma est affichée dans le browser, cliquer en haut à droite sur DEBUG
  3. Afficher les outils développeur:
    • Sous Firefox: on peut utiliser la raccourci [Ctrl] + [Maj] + [J] (sous MacOS: [⌘] + [Maj] + [J], sous Linux: [Ctrl] + [Maj] + [K]).
    • Sous Chrome: utiliser le raccourci [F12] (sous MacOS: [⌥] + [⌘] + [I], sous Linux: [Ctrl] + [Maj] + [I]).
    • Sous EDGE: utiliser le raccourci [F12].
  4. Aller dans l'onget "Sources"
  5. Taper [Ctrl]+[P] pour écrire le nom d'un fichier de code à débugguer
  6. Mettre un point d'arrêt dans le code du fichier <nom composant>.spec.ts.
  7. Recharger la page

Exécuter les tests de "bout en bout" (i.e. end-to-end)

Il faut lancer la commande:

ng e2e 

La configuration de ces tests se trouve dans e2e/protractor.conf.js. Par défaut, ces tests se trouvent dans le répertoire e2e/src dans des fichiers nommés <nom du fichier>.e2e-spec.ts.

Gérer des packages NPM

Installer un package NPM (ng add)

ng add <nom package> 

Les packages installés seront indiqués dans le fichier package.json avec les paramètres :

  • dependencies pour indiquer les packages utilisés pour le code déployé et pour le développement.
  • devDependencies pour indiquer les packages utilisés pour le développement seulement.

Mettre à jour un package NPM (ng update)

Sans options, la commande suivante permet d'indiquer les dépendances à mettre à jour et quelles sont les commandes à exécuter pour les mettre à jour:

ng udpate 

Pour mettre à jour un package spécifique:

ng update <nom package> <options> 

Pour que les mises à jour soient effectuées, il ne doit pas y avoir de fichiers modifiés et non commités (en sens Git).

Options Commentaires
Pour mettre à jour tous les packages présent dans le fichier package.json
--all
Forcer les mises à jour même en cas d'incompatibilité
--force
Indiquer une liste de packages à mettre à jour
--packages <liste des packages>
Forcer la mise à jour même dans le cas où des modifications n'ont pas été commitées
--allow-dirty

Pour d'autres commandes concernant les packages NPM, voir Les commandes npm courantes en 5 min.

Afficher les problèmes d'implémentation (ng lint)

Parcourt le code pour afficher les problèmes d'implémentation

ng lint 

Pour restreindre le parcours à un projet spécifique:

ng lint <nom du projet> 
Options Commentaires
Pour corriger les problèmes détectés
--fix 
Les fichiers sont modifiés
Pour changer la présentation des problèmes
--format <nom format>
Parmi les formats: json, stylish...
Pour exclure des fichiers lors du parcours
--exclude <chemin des fichiers à ignorer>
Le chemin peut contenir des wildcards.

Pour résumer...

Créer une nouvelle application
ng new <nom appli.> <options> 
ng n <nom appli.> <options> 
Détails | Documentation
Générer un nouvel élément Composant
ng g component <nom composant> 
ng g c <nom composant>
Détails | Documentation
Application
ng g application <nom appli.> 
ng g app <nom appli.> 
Détails | Documentation
Bibliothèque
ng g library <nom bibliothèque> 
ng g lib <nom bibliothèque> 
Détails | Documentation
Module
ng g module <nom module> 
ng g m <nom module> 
Détails | Documentation
Service
ng g service <nom service> 
ng g s <nom service>
Détails | Documentation
Classe
ng g class <nom classe> 
ng g cl <nom classe>
Détails | Documentation
Interface
ng g interface <nom interface> 
ng g i <nom interface> 
Détails | Documentation
Enum
ng g enum <nom enum> 
ng g e <nom enum> 
Détails | Documentation
Guard
ng g guard <nom guard> 
ng g g <nom guard>
Détails | Documentation
Pipe
ng g pipe <nom pipe> 
ng g p <nom pipe> 
Détails | Documentation
Construire une application
ng build <nom du projet> <options> 
ng b <nom du projet> <options> 
Détails | Documentation
Lancer un service web de développement
ng serve <options> 
ng s <options> 
Détails | Documentation
Exécuter une target
ng run <nom projet>:<nom de la target> 
Détails | Documentation
Exécuter des tests Exécuter des tests unitaires
ng test <nom du projet> <options> 
ng t <nom du projet> <options> 
Détails | Documentation
Exécuter les tests de "bout en bout"
ng e2e
Détails | Documentation
Gérer les packages NPM Installer un package
ng add <nom package> 
Détails | Documentation
Mettre à jour un package
ng update <nom package>
Détails | Documentation
Afficher les problèmes d'implémentation
ng lint 
Détails | Documentation

Leave a Reply