webpack-config-single-spa

8.0.0 verified Sat Apr 25 auth: no javascript

A webpack configuration preset for building in-browser microfrontend modules used with single-spa. Current stable version is 8.0.0, with a moderate release cadence following single-spa ecosystem updates. It simplifies webpack setup by automatically applying single-spa-specific plugins and loaders: sets output.libraryTarget to 'system', adds externals for single-spa dependencies, and configures standalone development mode. Compared to manual webpack configs, it reduces boilerplate and ensures compatibility with single-spa's module lifecycle and import map. Supports React, Angular, Vue, and generic JS modules via companion packages like webpack-config-single-spa-react and webpack-config-single-spa-ts.

Common errors

error TypeError: webpackConfigSingleSpa is not a function ↓

cause Using CommonJS require() which returns the module.exports object, but the package exports a default ES module function.

fix

Use import webpackConfigSingleSpa from 'webpack-config-single-spa' and ensure your package.json has "type": "module" or use .mjs extension.

error Module not found: Error: Can't resolve 'webpack' in '/path/to/project' ↓

cause Missing webpack peer dependency.

fix

Run npm install webpack@5 --save-dev

error System is not defined ↓

cause The generated config sets libraryTarget to 'system', so the module expects SystemJS at runtime, but SystemJS is not loaded in the browser.

fix

Load SystemJS (or single-spa's bundled version) in your HTML: <script src="https://unpkg.com/systemjs/dist/system.js"></script> and set up import map.

error Error: You gave us an object for the webpack config instead of a function. If you are using webpack-merge, make sure you are merging with a webpack config, not a function. ↓

cause Calling webpackConfigSingleSpa(options)() in v8 which expects direct call, not a second function call (v7 pattern).

fix

Change to: const config = webpackConfigSingleSpa(options);

Warnings

breaking Version 8.0.0 changed the default export signature. The function now returns a webpack configuration object directly instead of a function. Previous version required calling the returned function, e.g., webpackConfigSingleSpa({...})(). In v8, simply call webpackConfigSingleSpa({...}). ↓

fix If upgrading from v7, remove the extra function call: const config = webpackConfigSingleSpa(options) instead of webpackConfigSingleSpa(options)()

gotcha The package expects that webpack, single-spa, and related plugins are installed as peer dependencies. If missing, webpackConfigSingleSpa may fail with ModuleNotFoundError or missing plugin errors. ↓

fix Ensure all peer dependencies (webpack, single-spa, etc.) are installed: npm install webpack single-spa

gotcha The generated webpack config sets output.libraryTarget to 'system'. This means your module must be loaded by a SystemJS import map or single-spa's system loader. Trying to import it directly as a script tag will fail with 'System is not defined'. ↓

fix Use single-spa's import map or SystemJS to load your microfrontend. Alternatively, set output.libraryTarget to 'module' if using ES modules, but that requires different polyfills.

deprecated The 'type' option is deprecated in favor of 'moduleType' in v8. Using 'type' will still work but logs a warning and may be removed in future versions. ↓

fix Replace 'type' with 'moduleType' in your options object.

breaking Version 7.0.0 dropped support for webpack@4. Only webpack@5 is supported. Upgrading from webpack 4 requires webpack 5 and its new configuration format. ↓

fix Upgrade to webpack@5 and adjust your webpack config for version 5 changes (e.g., module.rules instead of module.loaders).

Install

npm install webpack-config-single-spa

yarn add webpack-config-single-spa

pnpm add webpack-config-single-spa

Imports

default

wrong

const webpackConfigSingleSpa = require('webpack-config-single-spa')

correct

import webpackConfigSingleSpa from 'webpack-config-single-spa'

ESM-only export. CommonJS require fails with TypeError: webpackConfigSingleSpa is not a function

webpackConfigSingleSpa

wrong

import { webpackConfigSingleSpa } from 'webpack-config-single-spa'

correct

import webpackConfigSingleSpa from 'webpack-config-single-spa'

This package has a default export, not a named export. Named import will be undefined.

webpackConfigSingleSpa

wrong

import * as webpackConfigSingleSpa from 'webpack-config-single-spa'

correct

import webpackConfigSingleSpa from 'webpack-config-single-spa'

Namespace import results in { default: ... } object; use default import directly.

Quickstart

Shows basic usage: import the default export, call it with options (projectRoot required), and optionally merge with webpack-merge to extend.

import webpackConfigSingleSpa from 'webpack-config-single-spa';
import webpack from 'webpack';

const config = webpackConfigSingleSpa({
  // Required: root project directory
  projectRoot: __dirname,
  // Optional overrides
  type: 'root', // or 'app' or 'parcel' depending on module type
  orgName: 'my-org',
  projectName: 'my-app',
});

// Merge with base webpack config (if needed)
const mergedConfig = webpack.merge(config, {
  // additional webpack config
});

export default mergedConfig;