React Cosmos Webpack Plugin

7.3.0 verified Sat Apr 25 auth: no javascript

The official Webpack plugin for React Cosmos (v7.3.0), a development tool for building isolated React component libraries and fixture-based testing. This plugin integrates React Cosmos with Webpack-based projects (e.g., Create React App, custom Webpack configs). React Cosmos 7 supports React 18/19 and Next.js 15, with a revamped UI, improved Vite plugin, and peer dependencies on react, react-dom, react-cosmos, and webpack. Releases follow a monthly cadence. Key differentiators: zero-config setup for Webpack, static prerendering support, and seamless integration with the Cosmos ecosystem for component-level development.

Common errors

error Error: Cannot find module 'react-cosmos-plugin-webpack' ↓

cause Package not installed or listed in dependencies.

fix

Run npm install react-cosmos-plugin-webpack --save-dev or yarn add react-cosmos-plugin-webpack --dev.

error TypeError: webpackPlugin is not a function ↓

cause Using CommonJS require without .default.

fix

Change const webpackPlugin = require('react-cosmos-plugin-webpack'); to const webpackPlugin = require('react-cosmos-plugin-webpack').default;.

error Module parse failed: Unexpected token (1:0) ↓

cause Webpack configuration missing loader for file type (e.g., SVG, TypeScript).

fix

Add appropriate Webpack rule in cosmos.config.js webpack override.

Warnings

breaking In React Cosmos 7, the plugin is ESM-first. Using CommonJS require() without accessing .default will fail. ↓

fix Use `const plugin = require('react-cosmos-plugin-webpack').default;` or switch to ESM imports.

deprecated The `webpack` config option in cosmos.config.js is deprecated in favor of using the plugin's own webpack config override. ↓

fix Pass webpack config override directly to the plugin via options, e.g., `[webpackPlugin({ config: { ... } })]`.

gotcha The plugin does not automatically detect webpack configuration; you must manually specify it via cosmos.config.js. ↓

fix Add `webpack: (config) => config` or use the plugin's built-in config handling.

gotcha If using TypeScript, ensure your cosmos.config.ts exports the config object correctly; common mistake: using `export default` without proper module interop. ↓

fix Use `export default require('react-cosmos-plugin-webpack').default` or use ESM imports.

Install

npm install react-cosmos-plugin-webpack

yarn add react-cosmos-plugin-webpack

pnpm add react-cosmos-plugin-webpack

Imports

react-cosmos-plugin-webpack

wrong

const reactCosmosWebpackPlugin = require('react-cosmos-plugin-webpack');

correct

import reactCosmosWebpackPlugin from 'react-cosmos-plugin-webpack'; // or require('react-cosmos-plugin-webpack').default

Since React Cosmos 7, the plugin is ESM-first. In CJS, use require('react-cosmos-plugin-webpack').default. TypeScript users should use default import.

reactCosmosWebpackPlugin
wrong
```
import { reactCosmosWebpackPlugin } from 'react-cosmos-plugin-webpack';
```
correct
```
const { reactCosmosWebpackPlugin } = require('react-cosmos-plugin-webpack');
```
Named export is not available; the module exports a default function. For named import, you must use CJS and destructure from default export, or use `import pkg from '...'` then access `pkg.default`.

default export

wrong

plugins: ['react-cosmos-plugin-webpack']

correct

// In cosmos.config.js:
export default {
  plugins: [require('react-cosmos-plugin-webpack').default]
}

The plugin configuration expects a function reference, not a string. Pass the imported plugin function directly.

Quickstart

Shows how to set up the Webpack plugin in cosmos.config.js, including a custom webpack config override to handle SVG files.

// cosmos.config.js
const webpackPlugin = require('react-cosmos-plugin-webpack').default;

module.exports = {
  plugins: [webpackPlugin],
  // Optional: webpack config override
  webpack: (config) => {
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    });
    return config;
  },
};

// Then run `npx cosmos` to start the Cosmos development server.