Конфигурация Angular workspace

Файл angular.json на корневом уровне Angular workspace предоставляет значения конфигурации по умолчанию для всего workspace и для конкретных проектов. Они используются инструментами сборки и разработки, предоставляемыми Angular CLI. Значения путей, указанные в конфигурации, относительны к корневому каталогу workspace.

Общая структура JSON

На верхнем уровне angular.json несколько свойств настраивают workspace, а секция projects содержит остальные опции конфигурации для каждого проекта. Значения Angular CLI по умолчанию, заданные на уровне workspace, можно переопределить значениями по умолчанию на уровне проекта. Также можно переопределить значения по умолчанию на уровне проекта с помощью командной строки.

Следующие свойства на верхнем уровне файла настраивают workspace.

Начальное приложение, созданное с ng new app-name, перечислено в «projects»:

Когда вы создаёте проект библиотеки с ng generate library, проект библиотеки также добавляется в секцию projects.

• Начальное приложение, созданное ng new, находится на верхнем уровне структуры файлов workspace.
• Другие приложения и библиотеки по умолчанию находятся в каталоге projects.

Дополнительную информацию см. в Структура файлов workspace и проекта.

Опции конфигурации Angular CLI

Следующие свойства — набор опций, настраивающих Angular CLI.

Опции Cache

Опции Warnings

Опции конфигурации проекта

Следующие свойства конфигурации верхнего уровня доступны для каждого проекта в projects['project-name'].

Опции i18n

Используйте опцию проекта i18n для определения исходной локали приложения и любых дополнительных локалей для сборки.

Объект sourceLocale

Передайте объект вместо строки, чтобы настроить выходной каталог или base HREF для исходной локали:

Объект Locale

Каждая запись locales может быть строкой пути, массивом путей или объектом:

Schematics

Angular schematics — инструкции по модификации проекта путём добавления новых файлов или изменения существующих. Их можно настроить, сопоставив имя schematic с набором опций по умолчанию.

«Имя» schematic имеет формат: <schematic-package>:<schematic-name>. Schematics для подкоманд ng generate Angular CLI по умолчанию собраны в пакете @schematics/angular. Например, schematic для генерации компонента с ng generate component — @schematics/angular:component.

Поля, указанные в схеме schematic, соответствуют разрешённым значениям аргументов командной строки и значениям по умолчанию для опций подкоманд Angular CLI. Можно обновить файл схемы workspace, чтобы задать другое значение по умолчанию для опции подкоманды. Например, чтобы по умолчанию отключить standalone в ng generate component:

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

Настройка CLI builders

Architect — инструмент, который Angular CLI использует для выполнения сложных задач, таких как компиляция и запуск тестов. Architect — оболочка, запускающая указанный builder для выполнения данной задачи согласно конфигурации цели. Можно определять и настраивать новые builders и цели для расширения Angular CLI. См. Angular CLI Builders.

Builders и цели Architect по умолчанию

Angular определяет builders по умолчанию для использования с конкретными командами или с общей командой ng run. JSON-схемы, определяющие опции и значения по умолчанию для каждого из этих builders, собраны в пакете @angular-devkit/build-angular. Схемы настраивают опции для следующих builders.

Настройка целей builder

Секция architect в angular.json содержит набор целей Architect. Многие цели соответствуют командам Angular CLI, которые их запускают. Другие цели можно выполнять с помощью команды ng run, и можно определять собственные цели.

Каждый объект цели указывает builder для этой цели — npm-пакет инструмента, который запускает Architect. У каждой цели также есть секция options, настраивающая опции по умолчанию для цели, и секция configurations, именующая и указывающая альтернативные конфигурации для цели. См. пример в Цель Build ниже.

Цель Build

Каждая цель в architect имеет следующие свойства:

Например, чтобы настроить сборку с отключёнными оптимизациями:

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

Альтернативные конфигурации сборки

Angular CLI поставляется с двумя конфигурациями сборки: production и development. По умолчанию команда ng build использует конфигурацию production, которая применяет несколько оптимизаций сборки, включая:

• Бандлинг файлов
• Минимизацию лишних пробелов
• Удаление комментариев и мёртвого кода
• Минификацию кода для использования коротких mangled имён

Можно определить и именовать дополнительные альтернативные конфигурации (например staging), подходящие вашему процессу разработки. Альтернативную конфигурацию можно выбрать, передав её имя флагу командной строки --configuration.

Например, чтобы настроить сборку, где оптимизация включена только для production-сборок (ng build --configuration production):

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

Также можно передать более одного имени конфигурации как список через запятую. Например, чтобы применить обе конфигурации сборки staging и french, используйте команду ng build --configuration staging,french. В этом случае команда разбирает именованные конфигурации слева направо. Если несколько конфигураций меняют одну и ту же настройку, финальным будет последнее установленное значение. В этом примере, если обе конфигурации staging и french задают выходной путь, будет использовано значение из french.

Дополнительные опции сборки и тестов

Настраиваемые опции для сборки по умолчанию или целевой сборки обычно соответствуют опциям, доступным для команд ng build и ng test. Подробности этих опций и их возможных значений см. в Справочнике Angular CLI.

Дополнительные опции serve

У dev-server есть собственный набор опций, обычно соответствующих опциям, доступным для команды ng serve.

Сложные значения конфигурации

Опции assets, index, outputPath, styles и scripts могут иметь либо простые строковые значения путей, либо значения-объекты с конкретными полями. Опции sourceMap и optimization можно установить в простое boolean-значение. Им также можно задать сложное значение с помощью файла конфигурации.

В следующих разделах подробнее о том, как эти сложные значения используются в каждом случае.

Конфигурация Assets

Каждая конфигурация цели build может включать массив assets, перечисляющий файлы или папки, которые вы хотите скопировать как есть при сборке проекта. По умолчанию содержимое каталога public/ копируется.

Чтобы исключить ресурс, можно удалить его из конфигурации assets.

Можно дополнительно настроить копируемые ресурсы, указывая assets как объекты, а не как простые пути относительно корня workspace. Объект спецификации asset может иметь следующие поля.

Например, пути assets по умолчанию можно представить подробнее с помощью следующих объектов.

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

Следующий пример использует поле ignore, чтобы исключить определённые файлы в каталоге assets из копирования в сборку:

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

Конфигурация Styles и scripts

Запись массива для опций styles и scripts может быть простой строкой пути или объектом, указывающим на дополнительный entry-point файл. Связанный builder загружает этот файл и его зависимости как отдельный бандл во время сборки. С объектом конфигурации есть возможность именовать бандл для entry point с помощью поля bundleName.

Бандл внедряется по умолчанию, но можно установить inject в false, чтобы исключить бандл из внедрения. Например, следующие значения-объекты создают и именуют бандл, содержащий стили и скрипты, и исключают его из внедрения:

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

Опции препроцессора стилей

В Sass можно использовать возможность includePaths и для компонентных, и для глобальных стилей. Это позволяет добавлять дополнительные базовые пути, проверяемые для импортов.

Чтобы добавить пути, используйте опцию stylePreprocessorOptions:

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

Файлы в этом каталоге, например src/style-paths/_variables.scss, можно импортировать откуда угодно в проекте без необходимости в относительном пути:

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

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

Конфигурация Optimization

Опция optimization может быть либо boolean, либо объектом для более тонкой настройки. Эта опция включает различные оптимизации вывода сборки, включая:

• Минификацию скриптов и стилей
• Tree-shaking
• Dead-code elimination
• Встраивание critical CSS
• Встраивание шрифтов

Несколько опций можно использовать для тонкой настройки оптимизации приложения.

Опции оптимизации Styles

Опции оптимизации Fonts

Можно передать значение вроде следующего, чтобы применить оптимизацию к одному или другому:

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

Конфигурация Source map

Опция builder sourceMap может быть либо boolean, либо объектом для более тонкой настройки управления source maps приложения.

Пример ниже показывает, как переключать одно или несколько значений для настройки вывода source map:

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

Source maps без содержимого источников

Можно генерировать source maps без поля sourcesContent, содержащего исходный код. Это позволяет разворачивать source maps в production для лучших отчётов об ошибках с исходными именами, защищая при этом исходный код от раскрытия.

Чтобы исключить содержимое источников из source maps, установите опцию sourcesContent в false:

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

Конфигурация Index

Настраивает генерацию HTML index приложения.

Опция index может быть либо строкой, либо объектом для более тонкой настройки.

При передаче значения как строки имя файла указанного пути будет использовано для сгенерированного файла, и он будет создан в корне настроенного выходного пути приложения.

Опции Index

Конфигурация выходного пути

Опция outputPath может быть либо String, которая будет использована как значение base, либо Object для более тонкой настройки.

Несколько опций можно использовать для тонкой настройки выходной структуры приложения.