<commit_before><p align="center">
  <img alt="Cosmos" src="cosmos.png">
</p>

<p align="center">
  <strong>React Cosmos</strong> ✭ Dev tool for creating reusable <a href="http://facebook.github.io/react/">React</a> components
</p>

<p align="center">
  <a href="https://travis-ci.org/react-cosmos/react-cosmos">
    <img alt="Build status" src="https://travis-ci.org/react-cosmos/react-cosmos.svg?branch=master">
  </a>
  <a href="https://coveralls.io/r/react-cosmos/react-cosmos?branch=master">
    <img alt="Coverage status" src="https://coveralls.io/repos/react-cosmos/react-cosmos/badge.svg?branch=master">
  </a>
  <a href="https://join-react-cosmos.now.sh/">
    <img alt="Slack" src="https://join-react-cosmos.now.sh/badge.svg">
  </a>
  <a href="https://spectrum.chat/cosmos">
    <img alt="Join the community on Spectrum" src="https://withspectrum.github.io/badge/badge.svg" />
  </a>
  <a href="CONTRIBUTING.md#how-to-contribute">
    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg">
  </a>
</p>

> **New: [Testing React Components](https://medium.com/@skidding/testing-react-components-30516bc6a1b3)** (with Cosmos)

Cosmos scans your project for components and enables you to:

1. Render components under any combination of props, context and state
2. Mock _every_ external dependency (eg. API responses, localStorage, etc)
3. See app state evolve in real-time while interacting with running instances

![Component Playground](intro.gif)

> Working with Cosmos improves component design because it surfaces dependencies. Cosmos forces us to define sane component inputs, making our UIs predictable and easier to debug down the road.

Read the story of React Cosmos: [Fighting for Component Independence](https://medium.com/@skidding/fighting-for-component-independence-2a762ee53272)

## Why Cosmos?

Many other component explorers emerged in the past years. [Storybook](https://github.com/storybooks/storybook) and [React Styleguidist](https://github.com/styleguidist/react-styleguidist) are good examples, but you can find an extensive list of options [here](https://react-styleguidist.js.org/docs/cookbook.html#are-there-any-other-projects-like-this). To decide which tool is best for you check for each project's goals, how much they match your needs, and how well the project is maintained.

**Cosmos is a dev tool first, made to improve _all_ components, big and small, not just the stateless UI bits.** The [fixture](#fixtures) and [proxy](#proxies) architecture doubles as an [automated testing utility](#headless-testing), providing a complete solution for developing robust and reusable components. Cosmos also makes it easy to create a living style guide, but it's a secondary goal and you might get more value from alternatives if this is your chief concern.

To find out more about the Cosmos project, check out [Mission](CONTRIBUTING.md#mission), [Goals](CONTRIBUTING.md#goals) and [Architecture](CONTRIBUTING.md#architecture).

## Usage

Requirements:

* [x] React >=0.14.9
* [x] webpack or Browserify (or roll your own integration)
* [ ] [Fixtures](#fixtures) (you'll create them after getting started)

React Cosmos works best with webpack. Making it work with other bundlers takes extra work, but a complete [Browserify example](examples/browserify) is available.

Jump to:

* **[Getting started](#getting-started)**
* [Fixtures](#fixtures)
  * [What's a fixture?](#whats-a-fixture)
  * [Where to put fixtures?](#where-to-put-fixtures)
  * [Props](#props)
  * [Children](#children)
  * [State](#state)
  * [Init hook](#init-hook)
  * [Fixture name and namespace](#fixture-name-and-namespace)
* [Proxies](#proxies)
  * [What's a proxy?](#whats-a-proxy)
  * [Where to put proxies?](#where-to-put-proxies)
  * [Context](#context)
  * [Redux](#redux)
  * [React Router](#react-router)
  * [React Apollo (GraphQL)](#react-apollo-graphql)
  * [Fetch](#fetch)
  * [XHR](#xhr)
  * [LocalStorage](#localstorage)
  * [More proxies...](#more-proxies)
* [Integration with popular tools](#integration-with-popular-tools)
  * [Create React App](#create-react-app)
  * [Next.js](#nextjs)
  * [React Boilerplate](#react-boilerplate)
  * [React Redux Starter Kit](#react-redux-starter-kit)
* [Config](#config)
  * [Custom config path](#custom-config-path)
  * [Custom webpack config](#custom-webpack-config)
  * [Custom fixture paths](#custom-fixture-paths)
  * [Option dump](#option-dump)
* [Exporting](#exporting)
* [Headless testing](#headless-testing)
  * [Using Enzyme](#using-enzyme)
  * [Using a custom renderer](#using-a-custom-renderer)
  * [Capturing state changes](#capturing-state-changes)
  * [Updating fixtures in tests](#updating-fixtures-in-tests)
  * [createTestContext API](#createtestcontext-api)
  * [Global Jest snapshot](#global-jest-snapshot)

_Have a question or idea to share? See you on [Slack](https://join-react-cosmos.now.sh/)._

### Getting started

Install via npm

```bash
npm install --save-dev react-cosmos
```

or Yarn

```bash
yarn add --dev react-cosmos
```

Add package.json scripts

```diff
"scripts": {
+  "cosmos": "cosmos"
+  "cosmos:export": "cosmos-export"
}
```

Run `npm run cosmos` or `yarn cosmos` and go to [localhost:8989](http://localhost:8989) 🎉

> If you rely on the default webpack config, make sure to install the Babel and webpack plugins yourself. Depending on your needs, you'll probably want `babel-preset-env babel-preset-react babel-loader style-loader css-loader html-webpack-plugin`. Finally, add `.babelrc` to your project root.
>
> ```
> {
>   "presets": ["env", "react"]
> }
> ```

#### Next steps

If everything's working

* **Create your first [fixture](#fixtures)**
* Configure or create [proxies](#proxies) (e.g. Redux integration)

If something's wrong

* Extend existing [webpack config](#custom-webpack-config)
* See [popular integrations](#integration-with-popular-tools) (e.g. CRA or Next.js)
* Extend your [config](#config)
* Be kind and [report what went wrong](https://github.com/react-cosmos/react-cosmos/issues)

### Fixtures

> **Old fixtures need to be adjusted to work with Cosmos v3**. Check out this [guide for upgrading](docs/fixture-upgrade.md).

#### What's a fixture?

A fixture is a JS object used to mock component input and external dependencies. The input can be [props](#props), [children](#children), [state](#state) and [context](#context). With the help of [proxies](#proxies), fixtures can mock anything else a component depends on, from API responses to localStorage.

```js
import Input from './Input';

export default {
  component: Input,
  props: {
    value: '<NAME>',
    disabled: true,
    onChange: value => console.log(`Select: ${value}`)
  }
};
```

> Check out this [quick hack](docs/fixtures.md) for getting started with fixtures.

#### Where to put fixtures?

Cosmos looks for `*.fixture.js` named files and files inside `__fixtures__` dirs by default. See [custom fixture paths](#custom-fixture-paths) for further customization.

It is also possible to export an array of fixtures from a single file. You may want to define the [fixture name and namespace](#fixture-name-and-namespace) in this case.

```js
export default [
  {
    component: Input,
    name: 'disabled',
    props: {
      disabled: true
    }
  },
  {
    component: Input,
    name: 'enabled',
    props: {
      disabled: false
    }
  }
];
```

#### Props

Mocking props is the most basic thing a fixture can do.

```js
export default {
  component: Auth,
  props: {
    loggedIn: true,
    user: {
      name: '<NAME>'
    }
  }
};
```

#### Children

Composition is the name of the game and many React components expect [children](https://facebook.github.io/react/docs/jsx-in-depth.html#children-in-jsx). You can specify your children just like you would any other prop:

```jsx
export default {
  component: Text,
  props: {
    someProp: true,
    children: (
      <div>
        <p>Fixture ain't afraid of JSX</p>
        <p>Fixture ain't afraid of nothin!</p><commit_msg>docs: Emphasise React needs to be in scope for JSX (#615)<commit_after><p align="center">
  <img alt="Cosmos" src="cosmos.png">
</p>

<p align="center">
  <strong>React Cosmos</strong> ✭ Dev tool for creating reusable <a href="http://facebook.github.io/react/">React</a> components
</p>

<p align="center">
  <a href="https://travis-ci.org/react-cosmos/react-cosmos">
    <img alt="Build status" src="https://travis-ci.org/react-cosmos/react-cosmos.svg?branch=master">
  </a>
  <a href="https://coveralls.io/r/react-cosmos/react-cosmos?branch=master">
    <img alt="Coverage status" src="https://coveralls.io/repos/react-cosmos/react-cosmos/badge.svg?branch=master">
  </a>
  <a href="https://join-react-cosmos.now.sh/">
    <img alt="Slack" src="https://join-react-cosmos.now.sh/badge.svg">
  </a>
  <a href="https://spectrum.chat/cosmos">
    <img alt="Join the community on Spectrum" src="https://withspectrum.github.io/badge/badge.svg" />
  </a>
  <a href="CONTRIBUTING.md#how-to-contribute">
    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg">
  </a>
</p>

> **New: [Testing React Components](https://medium.com/@skidding/testing-react-components-30516bc6a1b3)** (with Cosmos)

Cosmos scans your project for components and enables you to:

1. Render components under any combination of props, context and state
2. Mock _every_ external dependency (eg. API responses, localStorage, etc)
3. See app state evolve in real-time while interacting with running instances

![Component Playground](intro.gif)

> Working with Cosmos improves component design because it surfaces dependencies. Cosmos forces us to define sane component inputs, making our UIs predictable and easier to debug down the road.

Read the story of React Cosmos: [Fighting for Component Independence](https://medium.com/@skidding/fighting-for-component-independence-2a762ee53272)

## Why Cosmos?

Many other component explorers emerged in the past years. [Storybook](https://github.com/storybooks/storybook) and [React Styleguidist](https://github.com/styleguidist/react-styleguidist) are good examples, but you can find an extensive list of options [here](https://react-styleguidist.js.org/docs/cookbook.html#are-there-any-other-projects-like-this). To decide which tool is best for you check for each project's goals, how much they match your needs, and how well the project is maintained.

**Cosmos is a dev tool first, made to improve _all_ components, big and small, not just the stateless UI bits.** The [fixture](#fixtures) and [proxy](#proxies) architecture doubles as an [automated testing utility](#headless-testing), providing a complete solution for developing robust and reusable components. Cosmos also makes it easy to create a living style guide, but it's a secondary goal and you might get more value from alternatives if this is your chief concern.

To find out more about the Cosmos project, check out [Mission](CONTRIBUTING.md#mission), [Goals](CONTRIBUTING.md#goals) and [Architecture](CONTRIBUTING.md#architecture).

## Usage

Requirements:

* [x] React >=0.14.9
* [x] webpack or Browserify (or roll your own integration)
* [ ] [Fixtures](#fixtures) (you'll create them after getting started)

React Cosmos works best with webpack. Making it work with other bundlers takes extra work, but a complete [Browserify example](examples/browserify) is available.

Jump to:

* **[Getting started](#getting-started)**
* [Fixtures](#fixtures)
  * [What's a fixture?](#whats-a-fixture)
  * [Where to put fixtures?](#where-to-put-fixtures)
  * [Props](#props)
  * [Children](#children)
  * [State](#state)
  * [Init hook](#init-hook)
  * [Fixture name and namespace](#fixture-name-and-namespace)
* [Proxies](#proxies)
  * [What's a proxy?](#whats-a-proxy)
  * [Where to put proxies?](#where-to-put-proxies)
  * [Context](#context)
  * [Redux](#redux)
  * [React Router](#react-router)
  * [React Apollo (GraphQL)](#react-apollo-graphql)
  * [Fetch](#fetch)
  * [XHR](#xhr)
  * [LocalStorage](#localstorage)
  * [More proxies...](#more-proxies)
* [Integration with popular tools](#integration-with-popular-tools)
  * [Create React App](#create-react-app)
  * [Next.js](#nextjs)
  * [React Boilerplate](#react-boilerplate)
  * [React Redux Starter Kit](#react-redux-starter-kit)
* [Config](#config)
  * [Custom config path](#custom-config-path)
  * [Custom webpack config](#custom-webpack-config)
  * [Custom fixture paths](#custom-fixture-paths)
  * [Option dump](#option-dump)
* [Exporting](#exporting)
* [Headless testing](#headless-testing)
  * [Using Enzyme](#using-enzyme)
  * [Using a custom renderer](#using-a-custom-renderer)
  * [Capturing state changes](#capturing-state-changes)
  * [Updating fixtures in tests](#updating-fixtures-in-tests)
  * [createTestContext API](#createtestcontext-api)
  * [Global Jest snapshot](#global-jest-snapshot)

_Have a question or idea to share? See you on [Slack](https://join-react-cosmos.now.sh/)._

### Getting started

Install via npm

```bash
npm install --save-dev react-cosmos
```

or Yarn

```bash
yarn add --dev react-cosmos
```

Add package.json scripts

```diff
"scripts": {
+  "cosmos": "cosmos"
+  "cosmos:export": "cosmos-export"
}
```

Run `npm run cosmos` or `yarn cosmos` and go to [localhost:8989](http://localhost:8989) 🎉

> If you rely on the default webpack config, make sure to install the Babel and webpack plugins yourself. Depending on your needs, you'll probably want `babel-preset-env babel-preset-react babel-loader style-loader css-loader html-webpack-plugin`. Finally, add `.babelrc` to your project root.
>
> ```
> {
>   "presets": ["env", "react"]
> }
> ```

#### Next steps

If everything's working

* **Create your first [fixture](#fixtures)**
* Configure or create [proxies](#proxies) (e.g. Redux integration)

If something's wrong

* Extend existing [webpack config](#custom-webpack-config)
* See [popular integrations](#integration-with-popular-tools) (e.g. CRA or Next.js)
* Extend your [config](#config)
* Be kind and [report what went wrong](https://github.com/react-cosmos/react-cosmos/issues)

### Fixtures

> **Old fixtures need to be adjusted to work with Cosmos v3**. Check out this [guide for upgrading](docs/fixture-upgrade.md).

#### What's a fixture?

A fixture is a JS object used to mock component input and external dependencies. The input can be [props](#props), [children](#children), [state](#state) and [context](#context). With the help of [proxies](#proxies), fixtures can mock anything else a component depends on, from API responses to localStorage.

```js
import Input from './Input';

export default {
  component: Input,
  props: {
    value: 'Lorem ipsum',
    disabled: true,
    onChange: value => console.log(`Select: ${value}`)
  }
};
```

> Check out this [quick hack](docs/fixtures.md) for getting started with fixtures.

#### Where to put fixtures?

Cosmos looks for `*.fixture.js` named files and files inside `__fixtures__` dirs by default. See [custom fixture paths](#custom-fixture-paths) for further customization.

It is also possible to export an array of fixtures from a single file. You may want to define the [fixture name and namespace](#fixture-name-and-namespace) in this case.

```js
export default [
  {
    component: Input,
    name: 'disabled',
    props: {
      disabled: true
    }
  },
  {
    component: Input,
    name: 'enabled',
    props: {
      disabled: false
    }
  }
];
```

#### Props

Mocking props is the most basic thing a fixture can do.

```js
export default {
  component: Auth,
  props: {
    loggedIn: true,
    user: {
      name: '<NAME>'
    }
  }
};
```

#### Children

Composition is the name of the game and many React components expect [children](https://facebook.github.io/react/docs/jsx-in-depth.html#children-in-jsx). You can specify your children just like you would any other prop:

```jsx
// React needs to be in scope for JSX to work
import React from 'react';

export default {
  component: Text,
  props: {
    someProp: true,
    children: (
      <div>
        <p>Fixture ain't afraid of JSX</p>
        <p>Fixture ain't afraid of nothin!</p>
{'fraction_non_alphanumeric': 0.14298098953495572, 'fraction_numerical': 0.004272710384543935, 'mean_word_length': 4.426747311827957, 'pattern_counts': {'":': 8, '<': 68, '<?xml version=': 0, '>': 94, 'https://': 34, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '848038', 'n_tokens_mistral': 5367, 'n_tokens_neox': 5070, 'n_words': 1580}