scratch-webpack-configuration

3.1.2 verified Sat Apr 25 auth: no javascript

Shared webpack configuration builder for Scratch projects, version 3.1.2 as of March 2026. Provides a fluent API to construct webpack 5 configurations with defaults for Scratch's build pipeline, including Babel (with optional React), CSS (postcss-loader, css-loader, style-loader), TypeScript (ts-loader), asset modules via resource queries, chunk splitting, and target-specific externals for browserslist and Node. Released under BSD-3-Clause (was AGPL-3.0 in v2). Differentiators: opinionated but extensible via clone/merge, handles Scratch-specific module rules and externals, and integrates with Scratch's semantic release config. Requires webpack 5 and peer dependencies like @babel/preset-env, babel-loader, css-loader, postcss-loader, etc.

Common errors

error Error: Cannot find module 'scratch-webpack-configuration' ↓

cause Package not installed in node_modules.

fix

Run npm install scratch-webpack-configuration --save-dev

error TypeError: ScratchWebpackConfigBuilder is not a constructor ↓

cause Using named import instead of default import after switching to ESM.

fix

Change import { ScratchWebpackConfigBuilder } to import ScratchWebpackConfigBuilder

error Module not found: Error: Can't resolve 'css-loader' ↓

cause Missing peer dependency.

fix

npm install css-loader --save-dev

error BREAKING CHANGE: The license for this project has changed back to BSD-3-Clause ↓

cause Upgrading from v2 to v3 changes license.

fix

Update to v3 and review legal implications.

Warnings

deprecated v2.0.0 changed license from MIT to AGPL-3.0-only, then v3.0.0 reverted to BSD-3-Clause. ↓

fix Update to v3.0.0+ to use BSD-3-Clause license.

breaking v3.0.0 is ESM-only; CommonJS require() will throw. ↓

fix Use import syntax or dynamic import(). If you must use CommonJS, stay on v1.x (v2.x is also AGPL).

gotcha peer dependencies must be installed manually; the package does not auto-install them. ↓

fix Install all peer deps listed in the package.json. Missing css-loader/url-loader will cause build failures.

breaking v3.0.0 removed support for Node < 14; targets now require webpack 5. ↓

fix Ensure Node.js >=14 and webpack ^5.90.3.

gotcha When using enableReact: true, you must install @babel/preset-react separately. ↓

fix Add @babel/preset-react to devDependencies.

Install

npm install scratch-webpack-configuration

yarn add scratch-webpack-configuration

pnpm add scratch-webpack-configuration

Imports

ScratchWebpackConfigBuilder

wrong

const ScratchWebpackConfigBuilder = require('scratch-webpack-configuration');

correct

import ScratchWebpackConfigBuilder from 'scratch-webpack-configuration';

ESM-only since v3; CommonJS require will fail.

ScratchWebpackConfigBuilder
```
import ScratchWebpackConfigBuilder from 'scratch-webpack-configuration';
```
Default export, not named. TypeScript: use default import.

ScratchWebpackConfigBuilder

wrong

import { ScratchWebpackConfigBuilder } from 'scratch-webpack-configuration';

correct

import ScratchWebpackConfigBuilder from 'scratch-webpack-configuration';

Common mistake: using named import instead of default.

Quickstart

Shows creating a ScratchWebpackConfigBuilder, enabling React, setting target to browserslist, adding a CSS loader rule, and a CopyWebpackPlugin.

import ScratchWebpackConfigBuilder from 'scratch-webpack-configuration';

const builder = new ScratchWebpackConfigBuilder({
    rootPath: __dirname,
    enableReact: true
})
.setTarget('browserslist')
.addModuleRule({
    test: /\.css$/,
    use: ['style-loader', 'css-loader', 'postcss-loader']
})
.addPlugin(new (require('copy-webpack-plugin'))({
    patterns: [{ from: 'public' }]
}));

export default builder.get();