Canopy Webpack Config

4.4.3 verified Sat Apr 25 auth: no javascript

Opinionated webpack 5 defaults for Canopy micro-frontend services. Current stable version 4.4.3, maintained primarily for internal Canopy use. Provides automatic AMD output, externals for common dependencies (react, react-dom, luxon, react-hook-form, @canopytax/*), babel-loader integration, and bundle analysis via webpack-bundle-analyzer. Differentiator: handles sofe service externals out of the box, supports TypeScript via object option, and remains fully overrideable without ejecting. Release cadence is irregular, driven by internal needs. Requires webpack 5, babel-loader, @babel/runtime, @babel/plugin-transform-runtime.

Common errors

error Error: Cannot find module './externals' ↓

cause The externals feature expects a src/externals.ts or src/externals.js file to exist. If missing, webpack fails.

fix

Create a file at src/externals.ts (or .js) that exports an array of external module names, or disable the externals feature by not including it in your config.

error TypeError: canopyWebpackConfig is not a function ↓

cause Importing the package with ESM import instead of CommonJS require() or incorrectly calling the export.

fix

Use const canopyWebpackConfig = require('canopy-webpack-config'); and then call it as a function.

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

cause babel-loader is not included as a dependency and must be installed separately.

fix

Run yarn add --dev babel-loader or npm install --save-dev babel-loader.

Warnings

breaking In v4.0.0, webpack 5 upgrade removed unused-files-webpack-plugin and changed webpack-dev-server command to 'webpack serve'. ↓

fix If using webpack-dev-server, update scripts to use 'webpack serve' instead of 'webpack-dev-server'. Remove any references to unused-files-webpack-plugin.

breaking In v4.2.0, TypeScript option changed from boolean to an options object. Passing { typescript: true } breaks. ↓

fix Change { typescript: true } to { typescript: {} } or pass a configuration object.

gotcha Package does not install babel-loader or other loaders; you must install them separately. ↓

fix Add babel-loader, css-loader, etc. as devDependencies in your project and configure them in the override config.

gotcha Default export is a function that MUST be called with two arguments; simply exporting it as a config object will fail. ↓

fix Export the result of calling canopyWebpackConfig(name, overrides), not the function itself.

deprecated v4.1.1 fixed an overly aggressive externals rule that stripped all react-dom submodules. Users on 4.1.0 may have broken builds when using libraries like @floating-ui/react-dom. ↓

fix Upgrade to v4.1.1 or later.

Install

npm install canopy-webpack-config

yarn add canopy-webpack-config

pnpm add canopy-webpack-config

Imports

default

wrong

import canopyWebpackConfig from 'canopy-webpack-config';

correct

const canopyWebpackConfig = require('canopy-webpack-config');

Package uses CommonJS and does not support ESM imports. Use require() in Node.js environments.

default

wrong

module.exports = canopyWebpackConfig;

correct

const canopyWebpackConfig = require('canopy-webpack-config');
module.exports = canopyWebpackConfig('my-app', { /* overrides */ });

The default export is a function that takes two arguments (name, config). Calling it without arguments or forgetting the name parameter is a common mistake.

TypeScript usage

wrong

module.exports = canopyWebpackConfig('my-app', { typescript: true });

correct

const canopyWebpackConfig = require('canopy-webpack-config');
module.exports = canopyWebpackConfig('my-app', { typescript: {} });

Since v4.2.0, TypeScript support requires an options object (e.g., { typescript: {} }) instead of a boolean. Passing true will break.

Quickstart

Creates a webpack configuration for a Canopy service with custom CSS rule and output path, overriding defaults.

const canopyWebpackConfig = require('canopy-webpack-config');
const path = require('path');

module.exports = canopyWebpackConfig('my-app', {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  plugins: [
    // any custom plugins
  ],
});