README

Webpack Config: Web

Generates a Webpack 4 config for Web applications written in Typescript.

Example

package.json:

"scripts": {

    // Build for production mode
    "build": "webpack --mode production",

    // Development server mode
    "watch": "webpack-dev-server --mode development"
},
"dependencies": {

    // This package
    "@wildpeaks/webpack-config-web": "...",

    // Peer dependencies
    "typescript": "...",
    "webpack": "...",
    "webpack-cli": "...",
    "webpack-dev-server": "...",

    // Application-specific dependencies
    "unfetch": "..."
}

webpack.config.js:

'use strict';
const {join} = require('path');
const getConfig = require('@wildpeaks/webpack-config-web');

module.exports = function(_env, {mode = 'production'} = {}) {
    return getConfig({
        mode,
        entry: {
            myapp: './src/myapp.ts'
        },
        rootFolder: __dirname,
        outputFolder: join(__dirname, 'dist'),
        polyfills: [
            'core-js/stable/promise',
            'unfetch'
        ]
    });
};

Options

`mode`: String

Default: production.

Use production to optimize the output (CSS and JS files are minified), and the HTML script tags have Subresource Integrity hashes.

See Mode in the Webpack documentation.

`entry`: Object

Webpack entries.

Default: {}

Example:

{
    app1: './src/entry1.ts',
    app2: './src/entry2.ts',
    app3: './src/entry3.ts'
}

See Entry Points in the Webpack documentation.

`pages`: Object[]

List of HTML pages to generate.

Default: {title: 'Index', filename: "index.html"}.

When you have multiple pages, specify the chunks (id of the entries) to use in the page, otherwise it will use all entries in the page.

Examples:

// Single page
{
    pages: [
        {
            title: 'Index',
            filename: 'index.html'
        }
    ]
}

// Multiple pages
{
    entry: {
        app1: './src/first.ts',
        app2: './src/second.ts'
    },
    pages: [
        {
            title: 'First',
            filename: 'first-page.html',
            chunks: ['app1']
        },
        {
            title: 'Second',
            filename: 'second-page.html',
            chunks: ['app2']
        }
    ]
}

// Shared chunk
{
    entry: {
        app1: './src/first.ts',
        app2: './src/second.ts',
        shared: './src/extras.ts'
    },
    pages: [
        {
            title: 'First',
            filename: 'first-page.html',
            chunks: ['shared', 'app1']
        },
        {
            title: 'Second',
            filename: 'second-page.html',
            chunks: ['shared', 'app2']
        }
    ]
}

See Options in the html-webpack-plugin documentation.

`jsFilename`: String

Custom filename for JS bundles.

By default, files are named [name].js (development mode) or [hash].[name].js (production mode).

For example, this generates assets/scripts/app1.js:

{
    "entry": {
        "app1": "./src/example.ts"
    },
    "jsFilename": "assets/scripts/[name].js"
}

`jsChunkFilename`: String

Custom filename for JS chunks.

By default, files are named chunk.[id].js (development mode) or [hash].chunk.[id].js (production mode).

For example, this generates assets/scripts/chunk.0.js:

{
    "jsChunkFilename": "assets/scripts/chunk.[id].js"
}

`webworkerFilename`: String

Custom filename for Web Worker bundles.

By default, files are named [name].js (development mode) or [hash].[name].js (production mode).

For example, this generates assets/scripts/example.webworker.js for file example.webworker.js:

{
    "webworkerFilename": "assets/scripts/[name].js"
}

`cssFilename`: String

Custom filename for CSS bundles.

By default, files are named [name].css (development mode) or [hash].[name].css (production mode).

For example, this generates assets/stylesheets/app1.css:

{
    "entry": {
        "app1": "./src/example.ts"
    },
    "cssFilename": "assets/stylesheets/[name].css"
}

`cssChunkFilename`: String

Custom filename for CSS chunks.

By default, files are named chunk.[id].css (development mode) or [hash].chunk.[id].css (production mode).

For example, this generates assets/stylesheets/chunk.0.js:

{
    "cssChunkFilename": "assets/stylesheets/chunk.[id].js"
}

`assetFilename`: String

Custom filename for assets (images, json, etc..).

By default, files are named assets/[name].[ext] (development mode) or assets/[hash].[name].[ext] (production mode).

For example, this generates files/asset.image.jpg for file image.jpg:

{
    "assetFilename": "files/asset.[name].[ext]"
}

`rootFolder`: String

Absolute path to the root folder context. Defaults to the process current working directory.

Examples: "C:/Example" or /usr/share/www/example

See context in the Webpack documentation.

`outputFolder`: String

Absolute path to the output folder, where files are emitted.

Defaults to subfolder dist in rootFolder.

Example: "C:/Example/dist" or /usr/share/www/example/dist

See output.path in the Webpack documentation.

`publicPath`: String

Path prepended to url references.

Default: "/"

Example: "/mysite/"

See publicPath in the Webpack documentation.

`port`: Number

Port number for the Webpack Dev Server.

So port: 8000 means it runs at http://localhost:8000.

Default: 8000.

See devServer.port in the Webpack documentation.

`cssModules`: Boolean or String or Object

The CSS Modules option makes classnames and identifiers globally unique at build time, and importing a stylesheet returns an object with the generated unique classnames.

For example, two components could use a .button class. In regular CSS, this would conflict because one would overwrite the other. But this option renames both classes during the build, so they can co-exist.

Default: true.

See Modules in the css-loader documentation.

`scss`: String

Prepends arbitrary SCSS (or plain CSS) code to all .css and .scss files.

Useful for defining globals or adding a framework:

SCSS Variables for build-time variables
CSS Custom properties for runtime variables

Note: this is prepended to every file, so this is a good fit for theme variables. Use polyfills instead to add a CSS Reset (or :root CSS Variables) once per Entry.

Default: undefined.

Examples:

// Define SASS variables
{
    scss: `
        $primary: rgb(0, 255, 0);
        $secondary: rgb(0, 128, 0);
    `
}

// Import a SASS stylesheet
{
    scss: '@import "variables.scss";'
}

// Imports a CSS reset and multiple stylesheets from a framework
{
    polyfills: [
        './src/reset.css'
    ],
    scss: `
        @import "myframework/functions";
        @import "myframework/variables";
    `
}

// It can be a function too
// See https://github.com/webpack-contrib/sass-loader#function-1
{
    scss: (content, loaderContext) => "$primary: rgb(0, 255, 0);" + content
}

See:

CSS Custom Properties in MDN
SASS Variables in SASS documentation
Environment Variables in sass-loader documentation

`embedLimit`: number

Filesize limit to embed assets.

Beyond the limit, assets are considered external files (copied to the output folder and referenced by path).

Default: 5000.

See limit in the url-loader documentation.

`embedExtensions`: String[]

File extensions of files to embed as base64 (when small enough) or just copy as-is (when too large), for files referenced by import or require.

Default: ["jpg", "png", "gif", "svg"].

`rawExtensions`: String[]

File extensions of files to import as raw String, for files referenced by import or require.

Default: [].

Example: ["txt", "html", "md"].

`copyExtensions`: String[]

File extensions of files to just copy as-is, for files referenced by import or require.

Default: ["woff"].

`copyPatterns`: Object[]

Additional files & folders to copy as-is, despite not being referenced by import or require.

Default: [].

Examples:

// Copy a directory:
// "models/example.ext" is copied to "assets/example.ext"
{from: 'models', to: 'assets'}

// Copy specific files:
// "extras/models/example.gltf" is copied to "assets/extras/models/example.gltf"
{from: 'extras/**/*.gltf', to: 'assets'}

// Copy specific files:
// "extras/models/example.gltf" is copied to "assets/models/example.gltf"
{from: '**/*.gltf', to: 'assets', context: 'extras'}

// Ignore some files
{from: 'textures', to: 'assets', ignore: ['Thumbs.db']}

See patterns in the copy-webpack-plugin documentation.

`injectPatterns`: Object[]

List of pre-built scripts & stylesheets to inject in HTML.

Useful for large libraries (local or CDN), it drastically speeds up the build when they're not part of the build itself.

You can use copyPatterns to copy arbitrary files to the output if the injected patterns use relative paths instead of urls.

Note that the resulting script/link tags don't have automatic Subresource Integrity hashes, you should specify the hash manually using attributes (CDN hosts usually provide them along the urls).

Default: []

Examples:

// CDN urls and Subresource Integrity
{
    append: false,
    publicPath: false,
    tags: [
        {
            type: 'css',
            path: 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/css/bootstrap.min.css',
            attributes: {
                crossorigin: 'anonymous',
                integrity: 'sha384-WskhaSGFgHYWDcbwN70/dfYBj47jz9qbsMId/iRN3ewGhXQFZCSftd1LZCfmhktB'
            }
        },
        {
            type: 'js',
            path: 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/js/bootstrap.min.js',
            attributes: {
                crossorigin: 'anonymous',
                integrity: 'sha384-smHYKdLADwkXOn1EmN1qk/HfnUcbVRZyYmZ4qpPea6sjB/pTJ0euyQp0Mk8ck+5T'
            }
        }
    ]
}

// `append: false` to add at the beginning
{
    append: false,
    tags: ['thirdparty/three.min.js', 'thirdparty/OrbitControls.js']
}

// `append: true` to add at the end
{
    append: true,
    tags: ['override-styles.min.css']
}

See Options in the html-webpack-tags-plugin documentation.

`sourcemaps`: Boolean

Use true to generate sourcemaps for scripts & stylesheets, false to skip them.

Default: true

`polyfills`: String[]

List of modules or files to automatically prepend to every entry. They are resolved from rootFolder.

Default: ['core-js/stable/promise']

Note: given this accepts any extensions the loaders to, this can can also be used to prepend a CSS Reset.

// Example: ES6 Promise polyfill & a CSS Reset
{
    polyfills: [
        'core-js/stable/promise',
        './src/reset.css'
    ]
}

`webworkerPolyfills`: String[]

List of modules or files to automatically prepend to every webworker.

If you're using relative filepaths for polyfills instead of thirdparty modules or local modules, note that webworkerPolyfills references are resolved from each webworker unlike polyfills (because worker-loader doesn't have an option to have an array for its internal compilation, unlike main "entry" points, so the webworkerPolyfills references are imported directly in the code).

Default: ['core-js/stable/promise']

`webworkerPattern`: RegExp

RegExp test for the Web Worker loader.

Default: /\.webworker\.ts$/

`skipPostprocess`: Boolean

Use true for the lightweight config (for tests), false for the whole config.

Default: false

`skipHashes`: Boolean

If true, mode "production" won't add SRI hashes to <script> and <link> tags, and filenames will not contain a cache-busting hash.

Default: false

`skipReset`: Boolean

If true, it will not empty the output folder at the start. This is useful if you have multiple configs at the same time and are emptying the output folder before starting Webpack.

Default: false.

Import CSS / SCSS / Images

By default, Typescript doesn't know what importing CSS or images return.

This is not needed for building the bundles, but VSCode wouldn't have proper autocompletion. Therefore you should add generic type definitions (for example in /src/index.d.ts):

// CSS Modules Loader
declare module '*.css' {
    const _: {
        [key: string]: string;
    };
    export = _;
}
declare module '*.scss' {
    const _: {
        [key: string]: string;
    };
    export = _;
}

// URL Loader
declare module '*.jpg' {
    const _: string;
    export = _;
}
declare module '*.png' {
    const _: string;
    export = _;
}

This is already enough, but you can go even further with CSS Modules by typecasting it after import:

// "styles.css" contains classes `mybutton` and `mycontainer`
import * as rawCSS from './styles.css';

// Typecast to specify which properties exist
const typedCSS = rawCSS as {
    mybutton: string;
    mycontainer: string;
};

console.log( rawCSS.fake );        // the error is not detected
console.log( typedCSS.fake );      // the error is detected

CSS Autoprefixer

The property browsers has been removed in v3.0.0, but PostCSS can still autoprefix based on a browsers list.

Your project should either contain a .browserslistrc file, for example:

>0.25%
ie >= 11

or a browserlist section in your package.json, for example:

"browserslist": [
  ">0.25%",
  "ie >= 11"
]

More information at Browserslist.

Babel

Note that it intentionally doesn't use Babel because Typescript itself can already take care of transpiling to ES5 + ES Modules, and Webpack converts the ES Modules. This greatly reduces the number of dependencies and avoids limitations of the Typescript plugin for Babel.

However it also means it doesn't automatically include core-js dependencies. Therefore you can pass a list of polyfills to use (including polyfills that Babel wouldn't include and that you would have to add manually anyway) in options.

Usage no npm install needed!

README

Webpack Config: Web

Example

Options

mode: String

entry: Object

pages: Object[]

jsFilename: String

jsChunkFilename: String

webworkerFilename: String

cssFilename: String

cssChunkFilename: String

assetFilename: String

rootFolder: String

outputFolder: String

publicPath: String

port: Number

cssModules: Boolean or String or Object

scss: String

embedLimit: number

embedExtensions: String[]

rawExtensions: String[]

copyExtensions: String[]

copyPatterns: Object[]

injectPatterns: Object[]

sourcemaps: Boolean

polyfills: String[]

webworkerPolyfills: String[]

webworkerPattern: RegExp

skipPostprocess: Boolean

skipHashes: Boolean

skipReset: Boolean

Import CSS / SCSS / Images

CSS Autoprefixer

Babel

`mode`: String

`entry`: Object

`pages`: Object[]

`jsFilename`: String

`jsChunkFilename`: String

`webworkerFilename`: String

`cssFilename`: String

`cssChunkFilename`: String

`assetFilename`: String

`rootFolder`: String

`outputFolder`: String

`publicPath`: String

`port`: Number

`cssModules`: Boolean or String or Object

`scss`: String

`embedLimit`: number

`embedExtensions`: String[]

`rawExtensions`: String[]

`copyExtensions`: String[]

`copyPatterns`: Object[]

`injectPatterns`: Object[]

`sourcemaps`: Boolean

`polyfills`: String[]

`webworkerPolyfills`: String[]

`webworkerPattern`: RegExp

`skipPostprocess`: Boolean

`skipHashes`: Boolean

`skipReset`: Boolean