npm package: @nitro/webpack
Description: nitro webpack
Author: The Nitro Team
Latest version: 11.0.8

[![npm version](https://badge.fury.io/js/%40nitro%2Fwebpack.svg)](https://badge.fury.io/js/%40nitro%2Fwebpack)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
[![Build Status](https://github.com/merkle-open/generator-nitro/workflows/ci/badge.svg?branch=master)](https://github.com/merkle-open/generator-nitro/actions)

# Nitro Webpack

Configurable and easy to use webpack 5 config for nitro projects.

## Usage

```js
const options = {
    rules: {
        script: true,
        style: true,
        hbs: true,
        woff: true,
        font: false,
        image: true,
    },
    features: {
        banner: true,
        bundleAnalyzer: false,
        imageMinimizer: true,
        theme: false,
    },
};
const webpackConfig = require('@nitro/webpack/webpack-config/webpack.config.dev')(options);

module.exports = webpackConfig;
```

## Configuration

### Rules

No loader rule is enabled by default. Activate following prepared rules you need in `options.rules`

#### `options.rules.script`

- Type: boolean || object
- default: false
- file types: js, jsx, mjs, cjs (and optional ts, tsx, mts, cts)

Config:

- `true` or `{}` activates JavaScript support (via Babel)
- `{ typescript: true }` adds TypeScript support
- `{ babelConfigFile: 'path/to/babel.config.js' }` will be used as Babel config (default: auto-detect)
- `{ tsConfigFile: 'path/to/tsconfig.json' }` is used for type-checking with ForkTsCheckerWebpackPlugin (default: auto-detect)

#### `options.rules.style`

- Type: boolean || object
- default: false
- file types: scss, css

Config:

- `true` or `{}` will activate css & scss support
- `{ publicPath: '../' }` provide a separate public path for stylesheets. By default, webpack uses the value from 'output.publicPath'. (only relevant for production build)
- `{ sassOptions: { ... } }` gives the possibility to add options for the ['dart-sass'](https://sass-lang.com/documentation/js-api/interfaces/options/)

#### `options.rules.hbs`

- Type: boolean || object
- default: false
- file types: hbs

Config:

- `true` or `{}` will activate handlebars precompiled templates support
- `{ include: [] }` additionally adds include config to rule
- `{ exclude: [] }` additionally adds exclude config to rule

#### `options.rules.woff`

- Type: boolean || object
- default: false
- file types: woff, woff2

Config:

- `true` or `{}` will activate woff font support (in CSS files)
- `{ include: [] }` additionally adds include config to rule
- `{ exclude: [] }` additionally adds exclude config to rule

#### `options.rules.font`

- type: boolean || object
- default: false
- file types: eot, svg, ttf, woff, woff2

Config:

- `true` or `{}` will activate font support for eot, svg, ttf, woff & woff2 fonts (in CSS files)
- `{ include: [] }` additionally adds include config to rule
- `{ exclude: [] }` additionally adds exclude config to rule

⚠ Please use this rule with care. You have to configure includes and exclude when you also use woff and/or image loader.
Otherwise, svg or woff files are processed with multiple configurations.

#### `options.rules.image`

- Type: boolean || object
- default: false
- file types: png, jpg, gif, svg

Config:

- `true` will activate image support
- `{ include: [] }` additionally adds include config to rule
- `{ exclude: [] }` additionally adds exclude config to rule

### `options.features`

Enable some additional features

#### `options.features.banner`

- Type: boolean
- default: true

(only relevant for production build)

`true` will add a text banner with infos from package.json to the bundled js & css

#### `options.features.bundleAnalyzer`

- Type: boolean
- default: false

`true` will add the bundleAnalyser plugin and opens a browser window with the stats

#### `options.features.imageMinimizer`

- Type: boolean
- default: true

`false` will disable image minifaction functionality

#### `options.features.theme`

- Type: string || false
- default: false

A string will activate theming support:

- webpack uses `./src/ui.${theme}` as entrypoint (instead of `./src/ui`)
- a subfolder within assets is used for the output path and publicPath (`/assets/${theme}/`)

It makes sense to use a dynamic value e.g. an environment variable, as shown in the example configuration.

## Extending Configuration

### Code Splitting

By default, all js imports from 'node_modules' are extracted to a 'vendors.js' to use in your view files.

Dynamically imported js files will be extracted to `public/js/chunk/`.
You may use them in a promise chain.

```js
import('package-name').then((pack) => {
  // do something with 'pack'
});

import(
  /* webpackChunkName: "mychunk" */ 'package-name'
).then((pack) => {
  // do something with 'pack'
});
```

You may change the default configuration in [`webpackConfig.optimization.splitChunks`](https://webpack.js.org/configuration/optimization/#optimization-splitchunks)

## Changelog

Recent changes can be viewed on Github on the [Releases Page](https://github.com/merkle-open/generator-nitro/releases)