Configuration du workspace Angular

Le fichier angular.json, situé au niveau racine d'un workspace Angular, fournit des valeurs de configuration par défaut communes au workspace et spécifiques à chaque projet. Elles sont utilisées par les outils de build et de développement fournis par l'Angular CLI. Les chemins indiqués dans la configuration sont relatifs au répertoire racine du workspace.

Structure JSON générale

Au niveau racine de angular.json, quelques propriétés configurent le workspace et une section projects contient les autres options de configuration propres à chaque projet. Vous pouvez remplacer les valeurs par défaut de l'Angular CLI définies au niveau du workspace par des valeurs par défaut définies au niveau du projet. Vous pouvez aussi remplacer les valeurs par défaut définies au niveau du projet depuis la ligne de commande.

Les propriétés suivantes, au niveau racine du fichier, configurent le workspace.

L'application initiale que vous créez avec ng new app-name est listée sous « projects » :

Lorsque vous créez un projet de library avec ng generate library, ce projet de library est aussi ajouté à la section projects.

• L'application initiale créée par ng new se trouve au niveau racine de la structure de fichiers du workspace.
• Les autres applications et libraries se trouvent par défaut dans le répertoire projects.

Pour plus d'informations, consultez Structure des fichiers du workspace et des projets.

Options de configuration de l'Angular CLI

Les propriétés suivantes forment un ensemble d'options qui personnalisent l'Angular CLI.

Options du cache

Options des avertissements

Options de configuration des projets

Les propriétés de configuration de premier niveau suivantes sont disponibles pour chaque projet, sous projects['project-name'].

Options i18n

Utilisez l'option de projet i18n pour définir la locale source de l'application et les éventuelles locales supplémentaires à compiler.

Objet sourceLocale

Passez un objet plutôt qu'une chaîne pour personnaliser le répertoire de sortie ou la base HREF de la locale source :

Objet locale

Chaque entrée de locales peut être une chaîne de chemin, un tableau de chemins ou un objet :

Schematics

Les schematics Angular sont des instructions qui modifient un projet en ajoutant de nouveaux fichiers ou en modifiant des fichiers existants. Vous pouvez les configurer en associant le nom du schematic à un ensemble d'options par défaut.

Le « nom » d'un schematic suit le format <schematic-package>:<schematic-name>. Les schematics des sous-commandes ng generate par défaut de l'Angular CLI sont regroupés dans le package @schematics/angular. Par exemple, le schematic qui génère un composant avec ng generate component est @schematics/angular:component.

Les champs indiqués dans le schéma du schematic correspondent aux valeurs d'arguments de ligne de commande autorisées et aux valeurs par défaut des options de la sous-commande de l'Angular CLI. Vous pouvez modifier le fichier de schéma de votre workspace pour définir une autre valeur par défaut pour une option de sous-commande. Par exemple, pour désactiver standalone par défaut dans ng generate component :

{
  "projects": {
    "my-app": {
      "schematics": {
        "@schematics/angular:component": {
          "standalone": false
        }
      }
    }
  }
}

Configurer les builders de la CLI

Architect est l'outil qu'utilise l'Angular CLI pour effectuer des tâches complexes, comme la compilation et l'exécution des tests. Architect est une enveloppe qui exécute un builder donné pour effectuer une tâche précise, selon la configuration d'une cible. Vous pouvez définir et configurer de nouveaux builders et de nouvelles cibles pour étendre l'Angular CLI. Consultez Builders de l'Angular CLI.

Builders et cibles Architect par défaut

Angular définit des builders par défaut à utiliser avec des commandes précises, ou avec la commande générale ng run. Les schémas JSON qui définissent les options et les valeurs par défaut de chacun de ces builders sont regroupés dans le package @angular/build. Ces schémas configurent les options des builders suivants.

Configurer les cibles de builders

La section architect de angular.json contient un ensemble de cibles Architect. Beaucoup de ces cibles correspondent aux commandes de l'Angular CLI qui les exécutent. D'autres cibles peuvent être exécutées avec la commande ng run, et vous pouvez définir vos propres cibles.

Chaque objet cible indique le builder de cette cible, c'est-à-dire le package npm de l'outil qu'exécute Architect. Chaque cible possède aussi une section options qui configure les options par défaut de la cible, et une section configurations qui nomme et définit des configurations alternatives pour la cible. Consultez l'exemple de Cible de build ci-dessous.

Cible de build

Chaque cible sous architect possède les propriétés suivantes :

Par exemple, pour configurer un build avec les optimisations désactivées :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          }
        }
      }
    }
  }
}

Configurations de build alternatives

L'Angular CLI fournit deux configurations de build : production et development. Par défaut, la commande ng build utilise la configuration production, qui applique plusieurs optimisations de build, notamment :

• Le regroupement des fichiers en bundles
• La réduction des espaces superflus
• La suppression des commentaires et du code mort
• La minification du code avec des noms courts et obscurcis

Vous pouvez définir et nommer d'autres configurations alternatives (comme staging, par exemple) adaptées à votre processus de développement. Vous pouvez sélectionner une configuration alternative en passant son nom à l'option de ligne de commande --configuration.

Par exemple, pour configurer un build dans lequel l'optimisation n'est activée que pour les builds de production (ng build --configuration production) :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          },
          "configurations": {
            "production": {
              "optimization": true
            }
          }
        }
      }
    }
  }
}

Vous pouvez aussi passer plusieurs noms de configuration sous forme de liste séparée par des virgules. Par exemple, pour appliquer à la fois les configurations de build staging et french, utilisez la commande ng build --configuration staging,french. Dans ce cas, la commande analyse les configurations nommées de gauche à droite. Si plusieurs configurations modifient le même paramètre, la dernière valeur définie l'emporte. Dans cet exemple, si les configurations staging et french définissent toutes deux le chemin de sortie, c'est la valeur de french qui est utilisée.

Options supplémentaires de build et de test

Les options configurables d'un build par défaut ou ciblé correspondent généralement aux options disponibles pour les commandes ng build et ng test. Pour le détail de ces options et de leurs valeurs possibles, consultez la référence de l'Angular CLI.

Options supplémentaires de serve

Le serveur de développement dispose de son propre ensemble d'options, qui correspondent généralement aux options disponibles pour la commande ng serve.

Valeurs de configuration complexes

Les options assets, index, outputPath, styles et scripts acceptent soit de simples chaînes de chemin, soit des objets dotés de champs spécifiques. Les options sourceMap et optimization peuvent recevoir une simple valeur booléenne. Elles peuvent aussi recevoir une valeur complexe via le fichier de configuration.

Les sections suivantes détaillent l'utilisation de ces valeurs complexes dans chaque cas.

Configuration des assets

Chaque configuration de cible build peut inclure un tableau assets qui liste les fichiers ou dossiers à copier tels quels lors du build de votre projet. Par défaut, le contenu du répertoire public/ est copié.

Pour exclure une ressource, vous pouvez la retirer de la configuration des assets.

Vous pouvez configurer plus finement les ressources à copier en les spécifiant sous forme d'objets plutôt que de simples chemins relatifs à la racine du workspace. Un objet de spécification de ressource peut avoir les champs suivants.

Par exemple, les objets de ressources suivants copient le contenu de src/assets/ dans /assets/ et src/favicon.ico à la racine de la sortie.

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "output": "/assets/"
              },
              {
                "glob": "favicon.ico",
                "input": "src/",
                "output": "/"
              }
            ]
          }
        }
      }
    }
  }
}

L'exemple suivant utilise le champ ignore pour empêcher certains fichiers du répertoire des assets d'être copiés dans le build :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "ignore": ["**/*.svg"],
                "output": "/assets/"
              }
            ]
          }
        }
      }
    }
  }
}

Configuration des styles et des scripts

Une entrée de tableau des options styles et scripts peut être une simple chaîne de chemin ou un objet qui pointe vers un fichier de point d'entrée supplémentaire. Le builder associé charge ce fichier et ses dépendances dans un bundle distinct pendant le build. Avec un objet de configuration, vous pouvez nommer le bundle du point d'entrée à l'aide d'un champ bundleName.

Le bundle est injecté par défaut, mais vous pouvez définir inject à false pour exclure le bundle de l'injection. Par exemple, les objets suivants créent et nomment un bundle qui contient des styles et des scripts, et l'excluent de l'injection :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "styles": [
              {
                "input": "src/external-module/styles.scss",
                "inject": false,
                "bundleName": "external-module"
              }
            ],
            "scripts": [
              {
                "input": "src/external-module/main.js",
                "inject": false,
                "bundleName": "external-module"
              }
            ]
          }
        }
      }
    }
  }
}

Options des préprocesseurs de styles

Avec Sass, vous pouvez utiliser la fonctionnalité includePaths pour les styles des composants comme pour les styles globaux. Elle vous permet d'ajouter des chemins de base supplémentaires dans lesquels les imports sont recherchés.

Pour ajouter des chemins, utilisez l'option stylePreprocessorOptions :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src/style-paths"]
            }
          }
        }
      }
    }
  }
}

Les fichiers de ce répertoire, comme src/style-paths/_variables.scss, peuvent être importés depuis n'importe quel endroit de votre projet sans chemin relatif :

// A relative path works
@import '../style-paths/variables';

// But now this works as well
@import 'variables';

Configuration de l'optimisation

L'option optimization peut être soit un booléen, soit un objet pour une configuration plus fine. Cette option active diverses optimisations de la sortie du build, notamment :

• La minification des scripts et des styles
• Le tree-shaking
• L'élimination du code mort
• L'inlining du CSS critique
• L'inlining des polices

Plusieurs options permettent d'affiner l'optimisation d'une application.

Options d'optimisation des styles

Options d'optimisation des polices

Vous pouvez fournir une valeur comme la suivante pour appliquer l'optimisation à l'un ou à l'autre :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": {
              "scripts": true,
              "styles": {
                "minify": true,
                "inlineCritical": true
              },
              "fonts": true
            }
          }
        }
      }
    }
  }
}

Configuration des source maps

L'option de builder sourceMap peut être soit un booléen, soit un objet pour une configuration plus fine des source maps d'une application.

L'exemple ci-dessous montre comment basculer une ou plusieurs valeurs pour configurer les source maps produites :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": false,
              "hidden": true,
              "vendor": true
            }
          }
        }
      }
    }
  }
}

Source maps sans contenu source

Vous pouvez générer des source maps sans le champ sourcesContent, qui contient le code source d'origine. Cela vous permet de déployer des source maps en production pour un meilleur signalement des erreurs avec les noms source d'origine, tout en protégeant votre code source de toute exposition.

Pour exclure le contenu source des source maps, définissez l'option sourcesContent à false :

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": true,
              "sourcesContent": false
            }
          }
        }
      }
    }
  }
}

Configuration de l'index

Configure la génération de l'index HTML de l'application.

L'option index peut être soit une chaîne, soit un objet pour une configuration plus fine.

Lorsque la valeur est fournie sous forme de chaîne, le nom de fichier du chemin indiqué est utilisé pour le fichier généré, qui est créé à la racine du chemin de sortie configuré pour l'application.

Options de l'index

Configuration du chemin de sortie

L'option outputPath peut être soit une chaîne, utilisée comme valeur de base, soit un objet pour une configuration plus fine.

Plusieurs options permettent d'affiner la structure de sortie d'une application.