$commonSettings — Общие настройки

Настройки, не имеющие отношение к конкретной задаче или же имеющие отношение сразу к нескольким задачам могут быть определены в $projectBuilding.$commonSettings:

$projectBuilding:

  $commonSettings:

    # Задайте общие настройки здесь в соответствии с данным руководством

• $selectiveExecutions — Выборочные выполнения
  • Настройки каждого выборочного выполнения
    • $tasksAndSourceFilesSelection — выборка задачи и исходных файлов
    • $browserLiveReloadingSetupID — ID настроек автоматической перезагрузки вкладки браузера
    • $dockerSetupID — ID настроек Docker
    • $distributablePackageJSON_Generating — Генерация файла «package.json» для дистрибутива
    • $processingOnDemand — Обработка по требованию
      • enable — Нужно ли активировать
      • fullInitialBuilding　—　Требуется ли полная начальная сборка
• $publicDirectoriesRelativePaths — Относительные пути публичных директорий
• $filesWatching — Отслеживание файлов
  • excludeFilesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых файлов
  • excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых директорий
  • buildingModeDependent — В зависимости от режима сборки
    • excludeFilesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых файлов
    • excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых директорий

$selectiveExecutions — Выборочные выполнения

Объект типа «ассоциативный массив», с помощью которого осуществляется определение выборочных выполнений:

Через ключи указываются идентификаторы выборочных выполнений.

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      StaticPreview:

        # Конфигурация выборочного выполнения «StaticPreview» (подробности см. далее)

      Application:

        # Конфигурация выборочного выполнения «Application» (подробности см. далее)

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

После того, как валидные настройки выборочных выполнений определены , при вызове консольной утилиты yda через опцию --selectiveExecution можно указать один из объявленных в файле конфигурации идентификаторов выборочного выполнения, например:

yda build --selectiveExecution Application --mode LOCAL_DEVELOPMENT

Значениями ассоциативного массива $selectiveExecutions являются объекты, которые должны быть указаны в соответствие с описанными ниже правилами.

Настройки каждого выборочного выполнения

$tasksAndSourceFilesSelection — выборка задачи и исходных файлов

Объект типа «ассоциативный массив», ключами которого являются названия задач (но не всех, а только упомянутых в сводке выше), а значениями — массивы имён групп точек входа (в случае задач обработки исходного кода) или группы ассетов (в случае задач обработки ассетовили простого копирования файлов). При этом, все упомянутые в выборочном выполнении задачи и группы точек входа или ассетов должны быть объявлены в том же файле конфигурации:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      StaticPreview:

        $tasksAndSourceFilesSelection:

          $markupProcessing: [ StaticPreviewAnywherePage, Pages ]
          $stylesProcessing: [ Shared, Layouts, Pages ]

      Application:

        $tasksAndSourceFilesSelection:

          $markupProcessing: [ Pages, MVC_Fragments ]
          $stylesProcessing: [ Shared, Layouts, Pages ]

          $ECMA_ScriptLogicProcessing: [ Pages, FrontServerEntryPoint, TypeORM_Configuration ]

  $markupProcessing: # См. документацию по настройке обработки разметки
  
    $entryPointsGroups:
  
      StaticPreviewAnywherePage: # ...
  
      Pages: # ...
  
      MVC_Fragments: # ...
  
  $stylesProcessing: # См. документацию по настройке обработки стилей
  
    $entryPointsGroups:
  
      Shared: # ...
  
      Layouts: # ...
  
      Pages: # ...
  
  $ECMA_ScriptLogicProcessing: # См. документацию по настройке обработки ECMAScript-логики
  
    $entryPointsGroups:
  
      Pages: # ...
  
      FrontServerEntryPoint: # ...
  
      TypeORM_Configuration: # ...
  
  

$browserLiveReloadingSetupID — ID настроек автоматической перезагрузки вкладки браузера

Имеет отношение к функциональности автоматической перезагрузки браузера. API этой функциональности позволяет определить несколько пресетов, при этом каждому из них необходимо задать идентификатор. Тогда, если в конкретном выборочном выполнении затребована функциональность автоматической перезагрузки браузера, то через свойство $browserLiveReloadingSetupID требуется указать идентификатор нужного пресета:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      StaticPreview:

        $tasksAndSourceFilesSelection:

          # См. выше

        $browserLiveReloadingSetupID: StaticPreview

      Application:

        $tasksAndSourceFilesSelection:

          # См. выше

        $browserLiveReloadingSetupID: Application

  $browserLiveReloading:

    $setups:

      StaticPreview:

        # См. документацию по настройке автоматической перезагрузки браузера

      Application:

        # См. документацию по настройке автоматической перезагрузки браузера

$dockerSetupID — ID настроек Docker

Имеет отношение к функциональности интеграции с Docker. API этой функциональности позволяет определить несколько пресетов, при этом каждому из них необходимо задать идентификатор. Тогда, если в конкретном выборочном выполнении затребована функциональность интеграции с Docker, то для этого через свойство $dockerSetupID требуется указать идентификатор нужного пресета:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      SelectiveExecution1:

        $tasksAndSourceFilesSelection:

          # См. выше

        $dockerSetupID: DockerSetup1

      SelectiveExecution2:

        $tasksAndSourceFilesSelection:

          # См. выше

        $dockerSetupID: DockerSetup2


  $dockerLaunching:

    DockerSetup1:

      $composingOptions:

        # См. документацию по настройке запуска Docker

    DockerSetup2:

      $composingOptions:

        # См. документацию по настройке запуска Docker

$distributablePackageJSON_Generating — Генерация файла «package.json» для дистрибутива

Имеет отношение к функциональности генерации package.json для дистрибутива. Данный булевский флаг устанавливает, нужно ли для данного выборочного выполнения генерировать package.json, хотя если если не нужно, то можно просто не указывать эту опцию. Если же этот флаг установлен в значение true, то необходимо определить настройки одноимённой группы $distributablePackageJSON_Generating:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      Application:

        $distributablePackageJSON_Generating: true


  $distributablePackageJSON_Generating:

    # См. документацию по настройки выходного файла package.json

$processingOnDemand — Обработка по требованию

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

По умолчанию YDA при сохранении изменённых исходных файлов разметки обрабатывает только те точки входа, которые с этими файлами связаны Pug-директивами include и extends. Однако, во многих случаях этой меры оптимизации может оказаться недостаточно для того, чтобы предотвратить пересборку нескольких десятков точек входа после редактирования одного-двух Pug-файлов, что может стать помехой для продуктивной разработки. В этом случае можно активировать режим оптимизации, при котором обрабатывается только та точка входа, которая соответствуют открытой в браузере странице.

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

enable — Нужно ли активировать

Если указано значение true, то режим обработки по требованию будет включён. Если же нужно, чтобы данный режим был отключён, то в явном виде false можно не указывать, так как это значение по умолчанию.

fullInitialBuilding　—　Требуется ли полная начальная сборка

Если указано значение true, то в процессе начальной сборки проекта будут обработаны все точки входа, актуальные для текущего выборочного выполнения, что может занять некоторое время, если у вас несколько десятков точек входа. Значение по умолчанию — false, в этом случае конкретный Pug-файл будет обработан только тогда, когда соответствующий ему HTML-файл будет открыт в браузере, что хотя и не мгновенно, но обычно занимает порядка 2-3 секунд.

$publicDirectoriesRelativePaths — Относительные пути публичных директорий

Имеет отношение к функциональности вычисления указателей на ресурсы. Для того, чтобы вычислить укороченный абсолютный путь (невозможно для режима сборки статического превью в силу его концепции), необходимо указать, какой директории соответствует корень укороченного абсолютного пути. Эта директория должна быть указана в виде пути, относительного уже корневой директории проекта:

$projectBuilding:

  $commonSettings:

    $publicDirectoriesRelativePaths:

      $localDevelopment: 03-LocalDevelopmentBuild/public
      $staging: 04-StagingBuild/public
      $production: 05-ProductionBuild/public

$filesWatching — Отслеживание файлов

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

• Файлов и папок, имена которых начинаются с точки
• Следующих файлов:
  • package-lock.json
  • yarn.lock
• Следующих папок:
  • bin
  • node_modules
  • obj

Вдобавок к этому, следует исключить все файлы (или хотя бы большинство таковых), на изменения состояния которых YDA никак не должен реагировать. Сделать это можно как для обоих инкрементальных режимов сборки, так и для одного из них, причём в зависимости от режима сборки имеет смысл исключить из наблюдения выходные файлы для других режимов сборки.

excludeFilesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых файлов

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

excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых директорий

Имена директорий, которые будут исключены из наблюдения вне зависимости от того, на какой глубине они находится и какой именно инкрементальный режим сборки запущен. Здесь как правило имеет смысл исключить директории для продакшен-подобных сборок проекта.

buildingModeDependent — В зависимости от режима сборки

excludeFilesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых файлов

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

excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Относительные пути исключённых директорий

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

Рассмотрим следующий пример:

$projectBuilding:

  $commonSettings:

    #...

    $filesWatching:

      $excludeFilesWithPathsRelativeToProjectRootDirectory:

        - TestingBuild
        - StagingBuild
        - ProductionBuild

      $buildingModeDependent:

        $staticPreview:

          $excludeFilesWithPathsRelativeToProjectRootDirectory:

            - LocalDevelopmentBuild

        $localDevelopment:

          $excludeFilesWithPathsRelativeToProjectRootDirectory:

            - StaticPreviewBuild

• В директории TestingBuild, TestingBuild и ProductionBuild находятся сборки для соответствующих продакшен-подобных режимов. Отслеживать эти директории как правило смысла нет, потому они полностью проигнорированы.
• В случае режима сборки «статическое превью» нет смысла отслеживать сборку для режима локальной разработки, потому в режиме сборки «статическое превью» папка LocalDevelopmentBuild проигнорирована. Заметим, что если мы ещё и StaticPreviewBuild здесь же проигнорируем, то перезагрузка страницы браузера осуществляться не будет, так она осуществляется при изменении статуса файлов сборки.
• Для режима сборки «локальная разработка» наоборот, нет смысла отслеживать сборку для режима статического превью, потому папка StaticPreviewBuild проигнорирована.