Configuração do workspace Angular

O arquivo angular.json no nível raiz de um workspace Angular fornece padrões de configuração para todo o workspace e específicos de projeto. Estes são usados pelas ferramentas de build e desenvolvimento fornecidas pelo Angular CLI. Os valores de caminho fornecidos na configuração são relativos ao diretório raiz do workspace.

Estrutura geral do JSON

No nível superior do angular.json, algumas propriedades configuram o workspace e uma seção projects contém as opções de configuração restantes por projeto. Você pode sobrescrever os padrões do Angular CLI definidos no nível do workspace através de padrões definidos no nível do projeto. Você também pode sobrescrever padrões definidos no nível do projeto usando a linha de comando.

As seguintes propriedades, no nível superior do arquivo, configuram o workspace.

A aplicação inicial que você cria com ng new app-name é listada em "projects":

Quando você cria um projeto de biblioteca com ng generate library, o projeto de biblioteca também é adicionado à seção projects.

• A aplicação inicial criada por ng new está no nível superior da estrutura de arquivos do workspace.
• Outras aplicações e bibliotecas ficam sob o diretório projects por padrão.

Para mais informações, consulte Estrutura de arquivos do workspace e projeto.

Opções de configuração do Angular CLI

As seguintes propriedades são um conjunto de opções que personalizam o Angular CLI.

Opções de cache

Opções de avisos

Opções de configuração de projeto

As seguintes propriedades de configuração de nível superior estão disponíveis para cada projeto, em projects['project-name'].

Schematics

Angular schematics são instruções para modificar um projeto adicionando novos arquivos ou modificando arquivos existentes. Estes podem ser configurados mapeando o nome do schematic para um conjunto de opções padrão.

O "nome" de um schematic está no formato: <schematic-package>:<schematic-name>. Schematics para os sub-comandos ng generate padrão do Angular CLI são coletados no pacote @schematics/angular. Por exemplo, o schematic para gerar um component com ng generate component é @schematics/angular:component.

Os campos fornecidos no schema do schematic correspondem aos valores de argumentos de linha de comando permitidos e padrões para as opções do sub-comando do Angular CLI. Você pode atualizar seu arquivo de schema do workspace para definir um padrão diferente para uma opção de sub-comando. Por exemplo, para desabilitar standalone em ng generate component por padrão:

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

Configurando builders CLI

Architect é a ferramenta que o Angular CLI usa para realizar tarefas complexas, como compilação e execução de testes. Architect é um shell que executa um builder especificado para realizar uma determinada tarefa, de acordo com uma configuração de target. Você pode definir e configurar novos builders e targets para estender o Angular CLI. Consulte Angular CLI Builders.

Builders e targets Architect padrão

O Angular define builders padrão para uso com comandos específicos, ou com o comando geral ng run. Os schemas JSON que definem as opções e padrões para cada um desses builders são coletados no pacote @angular-devkit/build-angular. Os schemas configuram opções para os seguintes builders.

Configurando targets de builder

A seção architect do angular.json contém um conjunto de targets Architect. Muitos dos targets correspondem aos comandos do Angular CLI que os executam. Outros targets podem ser executados usando o comando ng run, e você pode definir seus próprios targets.

Cada objeto target especifica o builder para esse target, que é o pacote npm para a ferramenta que o Architect executa. Cada target também tem uma seção options que configura opções padrão para o target, e uma seção configurations que nomeia e especifica configurações alternativas para o target. Consulte o exemplo em Target de build abaixo.

Target de build

Cada target sob architect tem as seguintes propriedades:

Por exemplo, para configurar um build com otimizações desabilitadas:

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

Configurações alternativas de build

O Angular CLI vem com duas configurações de build: production e development. Por padrão, o comando ng build usa a configuração production, que aplica várias otimizações de build, incluindo:

• Empacotamento de arquivos
• Minimização de espaços em branco excessivos
• Remoção de comentários e código morto
• Minificação de código para usar nomes curtos e alterados

Você pode definir e nomear configurações alternativas extras (como staging, por exemplo) apropriadas ao seu processo de desenvolvimento. Você pode selecionar uma configuração alternativa passando seu nome para a flag de linha de comando --configuration.

Por exemplo, para configurar um build onde a otimização está habilitada apenas para builds de produção (ng build --configuration production):

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

Você também pode passar mais de um nome de configuração como uma lista separada por vírgulas. Por exemplo, para aplicar ambas as configurações de build staging e french, use o comando ng build --configuration staging,french. Neste caso, o comando analisa as configurações nomeadas da esquerda para a direita. Se várias configurações alterarem a mesma configuração, o último valor definido é o final. Neste exemplo, se ambas as configurações staging e french definirem o caminho de saída, o valor em french seria usado.

Opções extras de build e teste

As opções configuráveis para um build padrão ou direcionado geralmente correspondem às opções disponíveis para os comandos ng build e ng test. Para detalhes dessas opções e seus valores possíveis, consulte a Referência do Angular CLI.

Opções extras de serve

O servidor de desenvolvimento vem com seu próprio conjunto de opções que geralmente correspondem às opções disponíveis para o comando ng serve.

Valores de configuração complexos

As opções assets, index, outputPath, styles e scripts podem ter valores de caminho de string simples ou valores de objeto com campos específicos. As opções sourceMap e optimization podem ser definidas como um valor booleano simples. Elas também podem receber um valor complexo usando o arquivo de configuração.

As seções a seguir fornecem mais detalhes de como esses valores complexos são usados em cada caso.

Configuração de assets

Cada configuração de target build pode incluir um array assets que lista arquivos ou pastas que você deseja copiar como estão ao construir seu projeto. Por padrão, o conteúdo do diretório public/ é copiado.

Para excluir um asset, você pode removê-lo da configuração de assets.

Você pode configurar ainda mais os assets a serem copiados especificando assets como objetos, em vez de caminhos simples relativos à raiz do workspace. Um objeto de especificação de asset pode ter os seguintes campos.

Por exemplo, os caminhos de asset padrão podem ser representados em mais detalhes usando os seguintes objetos.

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

O exemplo a seguir usa o campo ignore para excluir certos arquivos no diretório de assets de serem copiados para o build:

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

Configuração de estilos e scripts

Uma entrada de array para as opções styles e scripts pode ser uma string de caminho simples, ou um objeto que aponta para um arquivo de ponto de entrada extra. O builder associado carrega esse arquivo e suas dependências como um bundle separado durante o build. Com um objeto de configuração, você tem a opção de nomear o bundle para o ponto de entrada, usando um campo bundleName.

O bundle é injetado por padrão, mas você pode definir inject como false para excluir o bundle da injeção. Por exemplo, os seguintes valores de objeto criam e nomeiam um bundle que contém estilos e scripts, e o excluem da injeção:

{  "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"              }            ]          }        }      }    }  }}

Opções de pré-processador de estilo

No Sass, você pode fazer uso do recurso includePaths tanto para estilos de component quanto globais. Isso permite adicionar caminhos base extras que são verificados para imports.

Para adicionar caminhos, use a opção stylePreprocessorOptions:

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

Arquivos nesse diretório, como src/style-paths/_variables.scss, podem ser importados de qualquer lugar em seu projeto sem a necessidade de um caminho relativo:

// src/app/app.component.scss// Um caminho relativo funciona@import '../style-paths/variables';// Mas agora isso também funciona@import 'variables';

Configuração de otimização

A opção optimization pode ser um booleano ou um objeto para configuração mais refinada. Esta opção habilita várias otimizações da saída do build, incluindo:

• Minificação de scripts e estilos
• Tree-shaking
• Eliminação de código morto
• Inlining de CSS crítico
• Inlining de fontes

Várias opções podem ser usadas para refinar a otimização de uma aplicação.

Opções de otimização de estilos

Opções de otimização de fontes

Você pode fornecer um valor como o seguinte para aplicar otimização a um ou outro:

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

Configuração de source map

A opção de builder sourceMap pode ser um booleano ou um objeto para configuração mais refinada para controlar os source maps de uma aplicação.

O exemplo abaixo mostra como alternar um ou mais valores para configurar as saídas de source map:

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

Source maps sem conteúdo de fontes

Você pode gerar source maps sem o campo sourcesContent, que contém o código fonte original. Isso permite que você faça deploy de source maps para produção para melhor relatório de erros com nomes de fonte originais enquanto protege seu código fonte de exposição.

Para excluir o conteúdo de fontes dos source maps, defina a opção sourcesContent como false:

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

Configuração de index

Configura a geração do HTML index da aplicação.

A opção index pode ser uma string ou um objeto para configuração mais refinada.

Ao fornecer o valor como uma string, o nome do arquivo do caminho especificado será usado para o arquivo gerado e será criado na raiz do caminho de saída configurado da aplicação.

Opções de index

Configuração do caminho de saída

A opção outputPath pode ser uma String que será usada como valor base ou um Objeto para configuração mais refinada.

Várias opções podem ser usadas para refinar a estrutura de saída de uma aplicação.