gaearon/cosmos

A foundation for maintainable web applications. Powered by React.

Cosmos

Cosmos is a React development utility built on top of:

1. ComponentTree — Serialize and reproduce the state of an entire tree of React components
2. ComponentPlayground — Minimal frame for loading and testing React components in isolation

Working with ComponentPlayground improves the component design because it surfaces any implicit dependencies. It also forces you to define sane inputs for every component, making them more predictable and easier to debug down the road.

There's no such thing as controllers or pages when working with Cosmos, just components. The UI is a tree of components consisting of a root component and its descendants. Moreover, any component can be loaded full-screen as the root element.

Requirements

• You should already be using CommonJS modules to structure your code and webpack to bundle your modules for the browser
• Your React components should be fully encapsulated. They should have no global dependencies and rely exclusively on props for input. Including styles, which means you need to be using style-loader.
• You must create component fixtures for ComponentPlayground to load. The component and fixture files should be nested as in the folder structure below. See the example repo for a better picture.

Installing

• Install the Cosmos package through npm npm install cosmos-js
• Run the ComponentPlayground executable node_modules/.bin/component-playground
• Open localhost:8989

Under the hood

Running the ComponentPlayground executable will:

1. Start a webpack dev server, serving an instance of ComponentPlayground at localhost:8989
2. Scan the current folder for components and fixtures and feed them to ComponentPlayground

The webpack build bundles modules from both the current folder and the Cosmos package. It is currently compatible with React classes, ES6 classes, JSX and CSS/LESS modules. In the future the webpack config should be configurable.

This is the file structure Cosmos expects:

|
+-- components
|   +-- FooComponent.jsx
|   +-- namespace
|   |   +-- BarComponent.jsx
+-- fixtures
|   +-- FooComponent
|   |   +-- default.js
|   |   +-- active.js
|   +-- namespace
|   |   +-- BarComponent
|   |       +-- default.js
|   |       +-- paused.js

If the components and fixtures folders are not siblings, their paths can be specified via cli args:

node_modules/.bin/component-playground --components-path src/components --fixtures-path tests/fixtures

Thank you for your interest!

Explore the wiki for more info on the Cosmos project.