@bolt/build-utils/config.schema.yml

Build-related utilities and helper scripts used in the Bolt Design System

# Thanks to StencilJS (https://stenciljs.com/docs/stencil-config) for a little inspiration for some of these configuration names. Naming things is hard!

  $schema: http://json-schema.org/draft-04/schema#
  title: Bolt Build Tools
  type: object
  required:
    - buildDir
    - components
  additionalProperties: false
  properties:
    namespace:
      type: string
      title: Namespace prefix to use in classnames
      default: 'bolt'
    lang:
      type: array, string
      title: Array of language-specific builds to generate. The 1st langugage specified is the default used for local development.
      default:
        - en
    mode:
      type: string
      title: Switches which context the Bolt build process and component rendering behavior should be compiling for -- either in the browser context (ie. client-side rendering) or in a Node.js server context (server-side rendering). This config is used to toggle server-side rendering functionality on and off.
      default: client
      enum:
        - client
        - server
    watch:
      type: boolean
      description: Configures internal tasks to watch for changes vs exiting when finished.
      default: false
    sourceMaps:
      type: boolean
      description: When set to true, generates sourcemaps when CSS and JS files are compiled.
      default: true
    i18n:
      type: boolean
      description: Should the design system's assets be compiled for multiple languages? Automatically defaults to false for local dev, true for prod.
    port:
      type: number
      title: Desired port for Browsersync server
      default: 3000
    hostname:
      type: string
      title: Desired host for Browsersync Proxy
      default: localhost
    proxyPort:
      type: number
      title: Desired port for Webpack Proxy
    proxyHostname:
      type: string
      title: Desired host for Webpack Proxy
    proxyHeader:
      type: string
      description: Special request header when proxying Webpack's dev server
      default: 'browsersync-proxy'
    templatesDir:
      type: array
      title: Template paths being added
      default:
        - templates
    copy:
      type: array
      description: The copy config is an array of objects specifying any files or folders that should get copied over to the build directory. Uses https://github.com/webpack-contrib/copy-webpack-plugin under the hood so any configuration options available there also apply here as well.
      items:
        type: object
        properties:
          from:
            type: [string, object]
            description: The files and/or directories to copy over
          to:
            type: [string, object]
            description: The destination of the files being copied over
          flatten:
            type: boolean
            description: Specify if any nested folders should get flattened down to a single level when copying over.
    globalData:
      type: object
      properties:
        js:
          $ref: '#/definitions/globalJsData'
        scss:
          $ref: '#/definitions/globalSassData'
    env:
      type: string
      title: Environment Type
      description: What is being compiled? Pattern Lab? Drupal? A static site? Or is the new in-progress Progressive Web App (PWA) that combines Pattern Lab + the docs site into one single environment?
      default: pwa
      enum:
        - pl
        - static
        - drupal
        - pwa
        - test
    renderingService:
      type: boolean
      description: Automatically start up the PHP / Twig Rendering Service?
      default: false
    renderingServicePort:
      type: number
      title: Desired port for PHP Rendering Service
      default: 8087
    alterTwigEnv:
      type: array
      description: Extends and alters the PHP-based Twig environment used when compiling Twig templates. Used for adding custom Twig extensions + [configuring environment options](https://twig.symfony.com/doc/1.x/api.html#environment-options). Passed directly to the @basalt/twig-renderer config option of same name.
    srcDir:
      type: string
      title: Source Directory
    webpackStats:
      type: boolean
      title: Write WebPack stats file
      description: Creates a [WebPack Stats Data file](https://webpack.js.org/api/stats/) called `webpack-stats.json` inside `buildDir`. Great for [this](http://webpack.github.io/analyse). Should probably run with `--prod`.
      default: false
    publicPath:
      type: string
      title: publicPath Directory
    plConfigFile:
      type: string
      title: Pattern Lab Config File Path
    buildDir:
      type: string
      description: The buildDir config specifies where Bolt's compiled files are saved after every build. These are the generated scripts which will be requested by the browser. The build directory should be relative to the wwwDir setting (i.e. inside it).
    wwwDir:
      type: string
      title: Path to server root
      description: "Where static files are served from. The wwwDir config specifies the public web distribution directory. This directory is commonly the root directory for a server, where all static files can be served. This directory is built and rebuilt directly from the source files. Note: We recommend this directory is not committed to a repository."
    iconDir:
      type: array
      description: The iconDir config specifies from where Bolt will be taking svg for icons creation.
    startPath:
      type: string
      title: Local server start path
      description: This is the `path/to/file.html` in `http://localhost:3000/path/to/file.html`
      default: '/'
    ip:
      type: string
      title: IP address internally populated. Used for local dev testing w/ Webpack Dev Server.
    webpackDevServer:
      type: boolean, object
      default: false
      description: WebPack Dev Server related config
      items:
        enabled:
          type: boolean
          description: Enables WebPack Dev Server.
        watchedExtensions:
          type: array
          description: Array of file extensions in the wwwDir that Webpack Dev Server will watch and trigger an HMR update when changed or added.
    enableCache:
      default: true
      type: boolean
      description: Caches the output from Webpack's build to significantly speed up the build tools after the first normal compile.
    dataDir:
      type: string
      description: This is the directory where generated json data files exist with information about the overall build. Defaults to `data` inside `buildDir`
    openServerAtStart:
      type: boolean
      default: false
      description: If, after starting `npm start`, a Browser opens.
    quick:
      type: boolean
      default: false
      description: Try to be quicker by skipping some steps that might not be needed if everything is recently built and in good working order.
    verbosity:
      type: integer
      default: 2
      description: Logging level (Range of 0 to 5) How 'loud' or 'quiet' do you want the console output to be?
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
    components:
      type: object
      properties:
        global:
          $ref: '#/definitions/components'
        individual:
          $ref: '#/definitions/components'
    extraTwigNamespaces:
      type: object
      title: Extra Twig Namespaces
      description: >-
        You can add Twig Namespaces using this and it serves two purposes:

        1. To add extra namespaces that have not been declared
        2. To add extra paths to previously declared namespaces

        Assuming we've already declared the `foo` namespaces to look in `~/my-dir1`.
        Then someone uses `extraNamespaces` to declare that `foo` will look in `~/my-dir2`
        This will not overwrite it, but *prepend* to the paths, resulting in a namespace setting like this:

        ```
        'foo': {
         paths: ['~/my-dir2', '~/my-dir1']
        }
        ```

        This causes the folder declared in `extraNamespaces` to be looked in first for templates, before our default; allowing end user developers to selectively overwrite some templates.

        Follows the conventions from [this plugin](https://packagist.org/packages/evanlovely/plugin-twig-namespaces).

    images:
      type: object
      description: Image resizing options, which can handle multiple sets.
      properties:
        sets:
          type: array
          items:
            type: object
            properties:
              base:
                type: string
                description: The base path, which is combined with `glob` to indicate the source file. The directories used here will *not* be used to construct the output path.
              glob:
                type: string
                description: The glob pattern, which can include plain directories, and is used to create the output path along with `dist`.
              dist:
                type: string
                description: The output path, which is combined with what `glob` returns.
    prod:
      type: boolean
      description: Production build, will compress assets.
      default: false
    schemaErrorReporting:
      description: Setting for where schema errors should be reported.  Note that reporting to cli will cause builds to fail if there are errors.
      type: string
      default: console
      enum:
        - none
        - console
        - cli
    configureWebpack:
      type: object
      description: 'Passing in an object will merge any config customizations with the default Bolt Webpack config (via <a href="https://github.com/survivejs/webpack-merge" target="_blank" rel="noopener">webpack-merge</a>).'
    configFileUsed:
      type: string
      description: The filepath to the `.boltrc` file used to load config. Programatically added to config.

  definitions:
    components:
      type: array
      items:
        oneOf:
          -
            type: string
          -
            type: object
            additionalProperties: false
            properties:
              name:
                type: string
                description: 'Becomes filename: NAME.css and NAME.js'
              scss:
                type: string
                title: Entry file for Sass. Import statements will be followed
              js:
                type: string
                title: Entry file for JS. Import statements will be followed
              required:
                - name
    globalJsData:
        type: array
        uniqueItems: true
        required:
          - items
        items:
          type: string
          description: '`.js` filename to pull in'
    globalSassData:
        type: array
        uniqueItems: true
        required:
          - items
        items:
          type: string
          description: '`.scss` filename to pull in'