React Cosmos Vite Plugin

7.3.0 verified Mon Apr 27 auth: no javascript

Official Vite plugin for React Cosmos, a development tool for building and testing React components in isolation. Version 7.3.0 supports React 18+, React 19, and Next.js 15. Actively maintained with monthly releases, it auto-generates a default index.html and auto-detects the main entry point. Key differentiator: seamless integration with React Cosmos's fixture and decorator system, enabling isolated component development without a full app setup. Requires react-cosmos >=7, vite, react, and react-dom as peer dependencies.

Common errors

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

cause The package is not installed or not in node_modules.

fix

Run npm install --save-dev react-cosmos-plugin-vite.

error TypeError: reactCosmosVitePlugin is not a function ↓

cause Incorrect import (default import instead of named import) or using require() in ESM context.

fix

Use import { reactCosmosVitePlugin } from 'react-cosmos-plugin-vite'.

error Error: The plugin requires at least Vite 4.0.0 ↓

cause Outdated Vite version.

fix

Upgrade Vite to version 4+ with npm install vite@latest.

error Error: 'react' must be version >=18.0.0 ↓

cause React version too old for v7 plugin.

fix

Upgrade React to 18 or later, or downgrade plugin to v6 (which supports React 17).

Warnings

breaking Version 7.0.0 removed support for React <18. Upgrade to React 18+ or stay on v6.x. ↓

fix Ensure react and react-dom are version 18 or higher. Alternatively, use react-cosmos-plugin-vite@6 if you need React 17.

gotcha The plugin auto-generates an index.html. If you have a custom index.html, it may conflict. Set the `indexHtml` option to disable auto-generation. ↓

fix In vite.config.ts: reactCosmosVitePlugin({ indexHtml: false }).

deprecated The `plugin` export was renamed to `reactCosmosVitePlugin` in v6.0.0. The old name still works but is deprecated. ↓

fix Use `reactCosmosVitePlugin` instead of `plugin`.

gotcha The plugin requires `react-dom` as a peer dependency even if you use React Native. Not installing react-dom will cause errors. ↓

fix Install react-dom: npm install react-dom.

Install

npm install react-cosmos-plugin-vite

yarn add react-cosmos-plugin-vite

pnpm add react-cosmos-plugin-vite

Imports

reactCosmosVitePlugin

wrong

import reactCosmosVitePlugin from 'react-cosmos-plugin-vite'

correct

import { reactCosmosVitePlugin } from 'react-cosmos-plugin-vite'

The plugin is a named export, not a default export. Use braces.

generateCosmosIndexHtml

wrong

const generateCosmosIndexHtml = require('react-cosmos-plugin-vite').generateCosmosIndexHtml

correct

import { generateCosmosIndexHtml } from 'react-cosmos-plugin-vite'

The package is ESM-only; require() is not supported.

defineConfig (from vite)

wrong

module.exports = { plugins: [require('react-cosmos-plugin-vite').reactCosmosVitePlugin()] }

correct

import { defineConfig } from 'vite'; import { reactCosmosVitePlugin } from 'react-cosmos-plugin-vite'; export default defineConfig({ plugins: [reactCosmosVitePlugin()] })

Vite config must be ESM in most setups; avoid CommonJS module.exports.

Quickstart

Shows how to configure Vite with the React Cosmos plugin, install peer dependencies, and start the Cosmos dev server.

// vite.config.ts
import { defineConfig } from 'vite';
import { reactCosmosVitePlugin } from 'react-cosmos-plugin-vite';

export default defineConfig({
  plugins: [reactCosmosVitePlugin()],
});

// Install peer dependencies:
// npm install --save-dev react-cosmos react-cosmos-plugin-vite vite react react-dom

// Run Cosmos:
// npx cosmos