Fractal Webpack Plugin

4.1.7 verified Sat Apr 25 auth: no javascript

A webpack plugin to integrate Fractal (a component library / styleguide tool) into a webpack build workflow. Current stable version is 4.1.7. It supports webpack 4 and 5, and Fractal 1.x. The plugin can either start a development server or build a static styleguide during webpack compilation. Key differentiators include simple configuration via a Fractal config file, seamless integration with webpack, and support for both server and build modes. Release cadence is irregular; last release was in 2023. Requires Node.js 10+.

Common errors

error TypeError: FractalWebpackPlugin is not a constructor ↓

cause Attempted to use import statement which may not resolve to the default export properly.

fix

Use const FractalWebpackPlugin = require('fractal-webpack-plugin');

error Error: Cannot find module 'fractal.config.js' ↓

cause The fractal config file is missing or the configPath option points to a non-existent file.

fix

Ensure the fractal config file exists at the specified path. Since v4.1.3, the default is 'fractal.config.js'.

error Error: Mode must be either 'server' or 'build' ↓

cause An invalid mode value was passed to the plugin options.

fix

Set mode to 'server' or 'build'.

Warnings

breaking Remove browsersync option from plugin (v3.0.0). Set it in fractal config file instead. ↓

fix Remove the 'browsersync' option from the plugin options and configure browsersync in your fractal.config.js if needed.

gotcha Default config filename changed from 'fractal.js' to 'fractal.config.js' in v4.1.3. If no configPath is specified, the plugin will look for 'fractal.config.js' first, and fall back to 'fractal.js'. ↓

fix Rename your fractal config file to 'fractal.config.js' or set the configPath option explicitly.

breaking Plugin requires webpack 4 or 5. It will not work with webpack 3 or earlier. ↓

fix Upgrade webpack to version 4 or 5.

gotcha The plugin does not provide a default export in ESM. Using import may fail in some bundlers. ↓

fix Use CommonJS require() or ensure your bundler handles CJS interop.

Install

npm install fractal-webpack-plugin

yarn add fractal-webpack-plugin

pnpm add fractal-webpack-plugin

Imports

FractalWebpackPlugin
wrong
```
import FractalWebpackPlugin from 'fractal-webpack-plugin';
```
correct
```
const FractalWebpackPlugin = require('fractal-webpack-plugin');
```
This package does not provide a default ESM export; use CommonJS require. If you must import, use: import FractalWebpackPlugin from 'fractal-webpack-plugin'; may work if your bundler handles CJS interop.
FractalWebpackPlugin
wrong
```
new FractalWebpackPlugin()
```
correct
```
new FractalWebpackPlugin({ mode: 'server' })
```
At least the mode option must be provided; default is 'server' but it's good practice to set it explicitly.
options
wrong
```
new FractalWebpackPlugin({ mode: 'server', configPath: 'fractal.js' })
```
correct
```
new FractalWebpackPlugin({ mode: 'build', configPath: './path/to/fractal.config.js' })
```
Since v4.1.3, the default config path is 'fractal.config.js', not 'fractal.js'. For backwards compatibility, 'fractal.js' is still accepted as a fallback, but you should use the new filename.

Quickstart

Demonstrates typical webpack config with FractalWebpackPlugin in build mode, using default config path.

const path = require('path');
const FractalWebpackPlugin = require('fractal-webpack-plugin');

module.exports = {
  entry: path.resolve('./src/index.js'),
  output: {
    path: path.resolve('./dist'),
    filename: 'bundle.js'
  },
  plugins: [
    new FractalWebpackPlugin({
      mode: 'build',
      configPath: './fractal.config.js'
    })
  ]
};