Skip to content

Latest commit

 

History

History
295 lines (215 loc) · 12.4 KB

configuration.md

File metadata and controls

295 lines (215 loc) · 12.4 KB

Configuration

(back to Readme)

Configuration File Location

A full list of available configuration options along with default values or direction are included in sample.kanopi-pack.json. @kanopi/pack searches your project directory for a JSON file named kanopi-pack.json or a CommonJS file called kanopi-pack.js, in either the root or assets/configuration folder. See a basic example of this in the Base No TypeScript example.

Configuration File Sections

The following sections allow customization with listed defaults and optional\required status.

Section: assets

Optional settings configure how different asset file types are handled. When an option is set for inlineFileTypes, they are removed for the list of Resources automatically.

Structure

"assets": {
    "inlineFileTypes": [],
    "resourceFileTypes": ['png', 'svg', 'jpg', 'jpeg', 'gif', 'woff', 'woff2', 'eot', 'ttf', 'otf'],
}

Details

Setting Default Required? Type Usage
inlineFileTypes [] No string string[]
resourceFileTypes 'png', 'svg', 'jpg', 'jpeg', 'gif', 'woff', 'woff2', 'eot', 'ttf', 'otf'] No string string[]

Section: devServer

Configure Webpack Dev Server, by default runs on 0.0.0.0:4400, with asset listing at http://0.0.0.0:4400/webpack-dev-server.

Structure

"devServer": {
    "allowedHosts": [],
    "host": "0.0.0.0",
    "port": 4400,
    "sockHost": "",
    "sockPort": 80,
    "useProxy": false,
    "watchOptions": {
        "aggregateTimeout": 600,
        "poll": false
    }
}

Details

Setting Default Required? Type Usage
allowedHosts '.localhost', 'localhost', '.docksal', '.test', '127.0.0.1' No String[] Add additional host names/IP(s) to the default list to access the server
host 0.0.0.0 No String Host Name/IP(s) of the server
port 4400 No Numeric Port of the server
sockHost No String Proxy Host Name/IP(s), sets publicPath of server assets
sockPort 80 No Numeric Proxy Host Port, set to 443 for SSL, only active if useProxy is enabled
useSslProxy false No Boolean Set true to enable SSL for the proxy, only active if useProxy is enabled
useProxy false No Boolean Set true to enable the proxy
watchOptions No Object -
watchOptions.aggregateTimeout 600 No Numeric Wait time (debounce) after a file change to process bundle changes
watchOptions.poll false No Boolean Set true to enable file system pooling, required for use in containers

Section: environment

Optional settings configure environment variables through Dotenv.

Structure

"environment": {
    "dotenvEnable": true,
    "dotenvConfiguration": {
        ... Dotenv options
    }
}

Details

Setting Default Required? Type Usage
dotenvConfiguration {} No Object Configuration for Dotenv, options here
dotenvEnable true No Boolean Set true to enable Dotenv

Section: externals

Optional settings to map externally loaded script libraries, useful if a CMS or Framework load these scripts external to these bundles.

Structure

"externals": {
    "jquery": "jQuery"
}

Details

List of key/value pair which match the Package name (i.e. 'jquery') to the its Global/Window location (i.e. 'jQuery' for window.jQuery). When using the function variant, the function is of the form function ({context, request}, callback) { ... }, see full details here.

Details

Setting Default Required? Type Usage
externals {"jquery": "jQuery"} No Object Function

Section: filePatterns

A map of input (entryPoints) file locations and output file path patterns.

Structure

"filePatterns": {
    "cssOutputPath": "css/[name].css",
    "entryPoints": {
        "scripts": "relative/path/to/file.js",
        "styles": "relative/path/to/file.scss"
    },
    "jsOutputPath": "js/[name].js",
    "staticAssetOutputName": "[name].[hash][ext][query]"
}

Details

Setting Default Required? Type Usage
cssOutputPath css/[name].css No String Output path for CSS files, accepts tokens like [name] and [hash]
entryPoints {} Yes ObjectMap[Name:FilePath] Map of [name] tokens to the entry file path; the project fails/exits if this is empty
jsOutputPath js/[name].js No String Output path for CSS files, accepts tokens like [name] and [hash]
staticAssetOutputName [name].[hash][ext][query] No String Output name for static files (like Fonts and Images), accepts tokens like [name], [ext] (contains the preceding .) and [hash]. Static files retain their relative path to the src directory so paths are consistent in the dist folder.

Section: minification

Configure minification of assets using Terser.

Structure

"minification": {
    "enable": true,
    "options": {
        "terserOptions": {
            "mangle": true,
           ... other Terser options ...
        }
    },
}

Details

Setting Default Required? Type Usage
enable true No Boolean Enable/disable minification of assets
options {} No Object Use the terserOptions sub-key for Terser options, outlined here

Section: paths

Settings for the asset structure, by default, all source assets are in the assets/src folder and all distribution assets are in the assets/dist folder, relative to the package/project root.

Structure

"paths": {
    "aliases": {
        "@": "./path/to/source_files/"
    },
    "assetsRelativeToRoot": "assets"
}

Details

Setting Default Required? Type Usage
aliases { '@': './assets/src/'} No Object List of string/symbol aliases to source folders; helps manage import/path references
assetsRelativeToRoot assets No String Containing folder for all assets, relative to the package/project root

Section: scripts

JavaScript and TypeScript related configuration.

Structure

"scripts": {
    "additionalResolveExtensions": "",
    "additionalTypescriptFileTypes": [],
    "esLintAutoFix": true,
    "esLintDisable": false,
    "esLintFileTypes": "js,jsx,ts,tsx",
    "useJsxSyntax": false
}

Details

Setting Default Required? Type Usage
additionalResolveExtensions No String Additional extensions which can be automatically use in JS import statements, added to .js, .ts, and .json. If Jsx is enabled, .jsx and .tsx are also enabled.
additionalTypescriptFileTypes No String Additional file types containing TypeScript, other than .ts
esLintAutoFix true No Boolean Enable to auto-fix source files on lint
esLintDisable false No Boolean Enable to disable ESLint through Webpack
esLintFileTypes js,jsx,ts,tsx No String Comma-delimited list of linted file extensions (no dot); overrides default
useJsxSyntax false No Boolean Enable to process JSX/TSX files through Babel

Section: sourceMaps

Production/distribution setting only, determines if these builds contain source maps. By default, this is disabled, and should be for most circumstances.

Structure

"sourceMaps": false

Section: styles

Style configuration options, especially related to StyleLint. By default, it uses the stylelint-config-property-sort-order-smacss order (Order package is installed) and a number of sensible rules common at Kanopi. Due to the default, configuration options are set relative to this modules path, and if you plan to install and extend a different rule set, configure styleLintConfigBaseDir to the package/project root directory. When extending, know that StyleLint uses CSS syntax only, by default, so you must add "customSyntax": "postcss-scss" to your custom configuration. Additionally, to ignore file globs, you must set a .stylelintignore in the package/project root directory.

Structure

"styles": {
    "devHeadSelectorInsertBefore": undefined,
    "postCssCustomizePluginOrder": undefined,
    "scssIncludes": [],
    "styleLintAutoFix": true,
    "styleLintConfigBaseDir": null,
    "styleLintConfigFile": null,
    "styleLintIgnorePath": null,
    "useSass": true
}

Details

Setting Default Required? Type Usage
devHeadSelectorInsertBefore undefined No String Specify a valid CSS selector in the document head, Dev Styles are inserted before it if present, or the bottom of the head tag when undefined or invalid
postCssCustomizePluginOrder undefined No String Object[]
postCssCustomParser undefined No String Set a custom parser for PostCSS, for instance, use postcss-scss to parse SCSS syntax
scssIncludes [] No String[] Set of SCSS files injected into each SCSS capable entry point
styleLintAutoFix true No Boolean When enabled, automatically fix source files according to StyleLint rules
styleLintConfigBaseDir node_modules/@kanopi/pack No String Relative path for StyleLint configuration options
styleLintConfigFile node_modules/@kanopi/pack/configuration/tools/stylelint.config.js No String Relative path for StyleLint configuration file
styleLintIgnorePath node_modules/@kanopi/pack/configuration/tools/.stylelintignore No String Relative path for a StyleLint ignore file
useSass true No Boolean When enabled, SASS styles are compiled

Available PostCSS Plugins

The following plugins are added by default, in the following order:

Overriding PostCSS plugins

In order to use a different set of PostCSS plugins OR add options to existing plugins, you can set the styles.postCssCustomizePluginOrder property. The following example keeps all of the available plugins in order, adding options to postcss-import and keeps the autoprefixer for grid enabled.

    "styles": {
        "postCssCustomizePluginOrder": [
          'postcss-import-ext-glob',
          [
            'postcss-import',
            {
              ... options
            }
          ],
          'postcss-mixins',
          'postcss-custom-selectors',
          'postcss-nested',
          'postcss-custom-media',
          [
            'postcss-preset-env',
            {
              autoprefixer: { 'grid': 'autoplace' }
            }
          ]
        ]
    }