Documentation
Webpack

Webpack

This is a guide for setting up React Cosmos in a Webpack project.

Getting Started

Install the required packages:

npm i -D react-cosmos react-cosmos-plugin-webpack

Create cosmos.config.json and enable the Webpack plugin:

cosmos.config.json
{
  "plugins": ["react-cosmos-plugin-webpack"]
}

Add cosmos and cosmos-export scripts to package.json:

package.json
"scripts": {
  "cosmos": "cosmos",
  "cosmos-export": "cosmos-export",
}

Create a basic fixture at src/Hello.fixture.jsx:

src/Hello.fixture.jsx
export default <h1>Hello World!</h1>;

Start React Cosmos:

npm run cosmos

🚀 Open localhost:5000 (opens in a new tab) in your browser.

The Hello fixture will show up in your Cosmos UI and will render when you select it.

Congratulations 😎

You've taken the first step towards designing reusable components. You're ready to prototype, test and interate on components in isolation.

Webpack Config

Cosmos generates a default Webpack config if a custom one isn't provided.

⚠️

Cosmos compiles your code using dependencies you already installed in your project. Cosmos will auto include common loaders like babel-loader, ts-loader, css-loader, etc. in the default Webpack config. Use a custom Webpack config for more advanced use cases.

⚠️

Make sure html-webpack-plugin is installed in your project.

💡

You may also need to create a .babelrc in your project root.

Custom Webpack Config

Probably the most common scenario. Most of us end up with a hairy Webpack config sooner or later.

Cosmos picks up webpack.config.js from the project root automatically. Use the webpack.configPath setting to provide an existing Webpack config at a different path:

cosmos.config.json
{
  "webpack": {
    "configPath": "./tools/webpack.config.js"
  }
}

You can also point to a module inside a dependency, like in the Create React App example.

Webpack Config Override

Overriding the Webpack config gives you complete control. Use the webpack.overridePath setting to point to a module that customizes the Webpack config used by Cosmos.

cosmos.config.json
{
  "webpack": {
    "overridePath": "./webpack.override.js"
  }
}

The override function receives a base Webpack config — the default one generated by Cosmos or a custom one loaded from webpack.configPath. Extend the input config and return the result.

webpack.override.js
module.exports = (webpackConfig, env) => {
  return { ...webpackConfig /* do your thing */ };
};

Output Filename

Cosmos overwrites output.filename in the Webpack config to [name].js by default. Due to caching, this isn't ideal when generating static exports via cosmos-export command. Use the webpack.includeHashInOutputFilename setting to change the filename template to [name].[contenthash].js.

cosmos.config.json
{
  "webpack": {
    "includeHashInOutputFilename": true
  }
}