React Cosmos — Sandbox for Developing and Testing UI Components

Introduction

React Cosmos is a development sandbox for building and testing React components in isolation. It lets developers render any component with specific props, state, and context, making it easier to develop, debug, and visually verify UI without running the full application.

What React Cosmos Does

• Renders React components in isolation with user-defined props and state fixtures
• Provides a visual explorer UI for browsing all component fixtures in a project
• Supports hot module replacement for instant feedback during development
• Enables component-level testing by exposing isolated render contexts
• Integrates with existing React projects without requiring architectural changes

Architecture Overview

React Cosmos uses a fixture-based approach. Developers create fixture files that define how a component should be rendered with specific props and context. The Cosmos server watches these files, bundles them with Webpack or Vite, and serves an interactive UI where each fixture can be previewed and manipulated. The architecture separates the renderer from the UI shell, supporting both DOM and custom render targets.

Self-Hosting & Configuration

• Install as a dev dependency and run with npx cosmos to launch the explorer
• Create fixture files alongside components using the .fixture.tsx naming convention
• Configure via cosmos.config.json for custom webpack/Vite settings and file patterns
• Deploy the static explorer build with npx cosmos-export for sharing with teams
• Works with Create React App, Next.js, Vite, and custom Webpack configurations

Key Features

• Fixture-driven development with declarative component state definitions
• Visual component explorer with search and filtering
• Decorator system for wrapping components with providers (themes, routers, stores)
• Responsive preview viewport for testing components at different screen sizes
• Plugin architecture for extending the explorer UI with custom panels

Comparison with Similar Tools

• Storybook — more ecosystem and addons; React Cosmos is lighter and fixture-based
• Ladle — Vite-native and fast; React Cosmos has a longer track record and plugin system
• Docz — focused on documentation; React Cosmos focuses on isolated development
• Styleguidist — combines docs with component rendering; Cosmos is development-first
• Bit — component sharing platform; React Cosmos is a local development sandbox

FAQ

Q: How is React Cosmos different from Storybook? A: Cosmos uses a fixture-based model instead of stories, resulting in less boilerplate. It emphasizes component isolation over documentation.

Q: Does it work with Next.js? A: Yes. React Cosmos supports Next.js projects with appropriate configuration for server components and routing.

Q: Can I use it for visual regression testing? A: You can export fixtures as static builds and integrate with visual testing tools like Playwright or Chromatic.

Q: Is it actively maintained? A: Yes. React Cosmos has been maintained since 2014 and continues to receive regular updates.

Sources

• https://github.com/react-cosmos/react-cosmos
• https://reactcosmos.org