$commonSettings — Common Settings

Settings that do not relate to a specific task or relate to several tasks can be defined in $projectBuilding.$commonSettings:

$projectBuilding:

  $commonSettings:

    # Define common settings here in accordance with this guide

• $selectiveExecutions — Selective Executions
  • Settings of Each Selective Execution
    • $tasksAndSourceFilesSelection — Selection of Tasks And Source Files
    • $browserLiveReloadingSetupID — Browser Live Reloading Setup ID
    • $dockerSetupID — Docker Setup ID
    • $distributablePackageJSON_Generating — Generating of "package.json" for the Distributive
    • $processingOnDemand — Processing on Demand
      • enable — Enable or no
      • fullInitialBuilding — Is Full Initial Building Required
• $publicDirectoriesRelativePaths — Public Directories Relative Paths
• $filesWatching — Files Watching
  • excludeFilesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Files
  • excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Directories
  • buildingModeDependent — Building Mode Dependent
    • excludeFilesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Files
    • excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Directories

$selectiveExecutions — Selective Executions

The object of associative array type used to define the selective executions.

The identifiers of selective executions must be specified via keys:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      StaticPreview:

        # Configuration of "StaticPreview" selective execution (see details below)

      Application:

        # Configuration of "Application" selective execution (see details below)

According to the settings definition convention, the absence of the $ character before these keys means that their names are user-chosen and are not  reserved keys in the API.

After valid settings for the selective executions have been defined , when invoking the CLI utility yda, via the --selectiveExecution option you can specify the one of selective executions identifiers declared in the configuration file, for example:

yda build --selectiveExecution Application --mode LOCAL_DEVELOPMENT

The values of the associative array $selectiveExecutions are objects that must be specified in accordance with the constraints given below.

Settings of Each Selective Execution

$tasksAndSourceFilesSelection — Selection of Tasks And Source Files

Object of type "associative array", keys of which are the names of tasks (but not all of them, only those mentioned in the abstract above), and the values are arrays of names of entry points groups (for tasks of processing source code) or assets groups (for tasks of processing assetsor simple file copying). Herewith, all tasks and groups of entry points or assets mentioned in the selective execution must be declared in the same configuration file:

$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: # See the documentation on configuring markup processing
  
    $entryPointsGroups:
  
      StaticPreviewAnywherePage: # ...
  
      Pages: # ...
  
      MVC_Fragments: # ...
  
  $stylesProcessing: # See the documentation on configuring styles processing
  
    $entryPointsGroups:
  
      Shared: # ...
  
      Layouts: # ...
  
      Pages: # ...
  
  $ECMA_ScriptLogicProcessing: # See the documentation on configuring ECMAScript logic processing
  
    $entryPointsGroups:
  
      Pages: # ...
  
      FrontServerEntryPoint: # ...
  
      TypeORM_Configuration: # ...
  
  

$browserLiveReloadingSetupID — Browser Live Reloading Setup ID

Relates to the automatic browser reloading functionality. The API of this functionality allows defining several presets, and each of them must have an identifier. Then, if a particular selective execution requires the browser live reloading functionality, via the property $browserLiveReloadingSetupID you must specify the identifier of the required preset:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      StaticPreview:

        $tasksAndSourceFilesSelection:

          # See above

        $browserLiveReloadingSetupID: StaticPreview

      Application:

        $tasksAndSourceFilesSelection:

          # See above

        $browserLiveReloadingSetupID: Application

  $browserLiveReloading:

    $setups:

      StaticPreview:

        # See the configuring browser live reloading documentation

      Application:

        # See the configuring browser live reloading documentation

$dockerSetupID — Docker Setup ID

Relates to the integration with Docker functionality. The API of this functionality allows defining several presets, and each of them must have an identifier. Then, if a particular selective execution requires the Docker functionality, via the property $dockerSetupID you must specify the identifier of the required preset:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      SelectiveExecution1:

        $tasksAndSourceFilesSelection:

          # See above

        $dockerSetupID: DockerSetup1

      SelectiveExecution2:

        $tasksAndSourceFilesSelection:

          # See above

        $dockerSetupID: DockerSetup2


  $dockerLaunching:

    DockerSetup1:

      $composingOptions:

        # See the configuring Docker launching documentation

    DockerSetup2:

      $composingOptions:

        # See the configuring Docker launching documentation

$distributablePackageJSON_Generating — Generating of "package.json" for the Distributive

Relates to the functionality of generating package.json for the distributable. This boolean flag defines whether for this selective execution package.json should be generated, although if it is not needed, you can simply omit this option. If this flag is set to true, then you must define the settings of the homonymous group $distributablePackageJSON_Generating:

$projectBuilding:

  $commonSettings:

    $selectiveExecutions:

      Application:

        $distributablePackageJSON_Generating: true


  $distributablePackageJSON_Generating:

    # See the documentation on configuring the output package.json file

$processingOnDemand — Processing on Demand

Relates to the optimization functionality of the markup processing on demand, and also to the browser live reloading. Therefore, this group of settings is relevant only for incremental project building modes.

By default, when saving changed source markup files, YDA processes only those entry points that are related to these files via Pug directives include and extends. However, in many cases, this optimization measure may not be enough to prevent the rebuilding of several dozen entry points after editing one or two Pug files, which can hinder productive development. In this case, you can activate the optimization mode where only the entry point corresponding to the page open in the browser is processed.

This section discusses the processing on demand settings relevant to a specific selective execution; however, these same settings can also be defined globally (independent of selective executions).

enable — Enable or no

If has been set with true, then the processing on demand mode will be enabled. If you want this mode to be disabled, you can explicitly specify false, but it is the default value.

fullInitialBuilding — Is Full Initial Building Required

If the value is true, then during the initial project build process, all entry points relevant to the current selective execution will be processed, which may take some time if you have several dozen entry points. The default value is false; in this case, a specific Pug file will be processed only when its corresponding HTML file is opened in the browser, which, although not instantaneous, usually takes about 2-3 seconds.

$publicDirectoriesRelativePaths — Public Directories Relative Paths

Relates to the functionality of resource pointers resolving. In order to resolve the shortened absolute path (impossible for the build mode static preview due to its concept), it is necessary to specify which directory corresponds to the root of the shortened absolute path. This directory must be specified as a path relative to the project directory:

$projectBuilding:

  $commonSettings:

    $publicDirectoriesRelativePaths:

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

$filesWatching — Files Watching

For project rebuilding as well as automatic reloading of the browser page in incremental building modes, it is necessary to watch the state of files and directories. By default, all files and directories below the directory containing the YDA configuration file are watched, except:

• Files and directories whose names start with a dot
• The following files:
  • package-lock.json
  • yarn.lock
• The following directories:
  • bin
  • node_modules
  • obj

In addition to this, all files (or at least most of them) to whose state changes YDA should not react in any way should be excluded. This can be done either for both incremental building modes or for one of them; moreover, depending on the building mode, it makes sense to exclude from watching the output files for other building modes.

excludeFilesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Files

The names of files that will be excluded from the watching regardless of the depth at which they are located and which specific incremental building mode is running.

excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Directories

The names of directories that will be excluded from the watching regardless of the depth at which they are located and which specific incremental building mode is running. Here usually it makes sense to exclude directories for production-like project builds.

buildingModeDependent — Building Mode Dependent

excludeFilesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Files

The names of files that will be excluded regardless of the depth at which they are located, but only for the specified building mode.

excludeDirectoriesWithPathsRelativeToProjectRootDirectory — Relative Paths of Excluded Directories

The names of directories that will be excluded regardless of the depth at which they are located, but only for the specified building mode.

Consider the following example:

$projectBuilding:

  $commonSettings:

    #...

    $filesWatching:

      $excludeFilesWithPathsRelativeToProjectRootDirectory:

        - TestingBuild
        - StagingBuild
        - ProductionBuild

      $buildingModeDependent:

        $staticPreview:

          $excludeFilesWithPathsRelativeToProjectRootDirectory:

            - LocalDevelopmentBuild

        $localDevelopment:

          $excludeFilesWithPathsRelativeToProjectRootDirectory:

            - StaticPreviewBuild

• The TestingBuild, StagingBuild, and ProductionBuild directories contain builds for the corresponding production-like modes. Usually, there is no need to watch these directories, so they are completely ignored.
• For the static preview building mode case, there is no point in watching the build for the local development mode, so for static preview building mode LocalDevelopmentBuild directory is ignored. Note that if we also ignore StaticPreviewBuild here, the browser page live reloading will not occur, since it is performed when the status of build files changes.
• For the "local development" building mode, conversely, there is no point in watching the build for the static preview mode, so the StaticPreviewBuild directory is ignored.