<commit_before># Cookbook

<!-- To update run: npx markdown-toc --maxdepth 2 -i docs/Cookbook.md -->

<!-- toc -->

* [How to use `ref`s in examples?](#how-to-use-refs-in-examples)
* [How to exclude some components from style guide?](#how-to-exclude-some-components-from-style-guide)
* [How to hide some components in style guide but make them available in examples?](#how-to-hide-some-components-in-style-guide-but-make-them-available-in-examples)
* [How to set global styles for user components?](#how-to-set-global-styles-for-user-components)
* [How to add custom JavaScript and CSS or polyfills?](#how-to-add-custom-javascript-and-css-or-polyfills)
* [How to use React Styleguidist with Preact?](#how-to-use-react-styleguidist-with-preact)
* [How to change styles of a style guide?](#how-to-change-styles-of-a-style-guide)
* [How to change the layout of a style guide?](#how-to-change-the-layout-of-a-style-guide)
* [How to change style guide dev server logs output?](#how-to-change-style-guide-dev-server-logs-output)
* [How to debug my components and examples?](#how-to-debug-my-components-and-examples)
* [How to debug the exceptions thrown from my components?](#how-to-debug-the-exceptions-thrown-from-my-components)
* [How to use React's production or development build?](#how-to-use-reacts-production-or-development-build)
* [Why does the style guide list one of my prop types as `unknown`?](#why-does-the-style-guide-list-one-of-my-prop-types-as-unknown)
* [Why object references don’t work in example component state?](#why-object-references-dont-work-in-example-component-state)
* [How to use Vagrant with Styleguidist?](#how-to-use-vagrant-with-styleguidist)
* [How to add external JavaScript and CSS files?](#how-to-add-external-javascript-and-css-files)
* [How to reuse project’s webpack config?](#how-to-reuse-projects-webpack-config)
* [How to use React Styleguidist with Redux, Relay or Styled Components?](#how-to-use-react-styleguidist-with-redux-relay-or-styled-components)
* [What’s the difference betweeen Styleguidist and Storybook](#whats-the-difference-betweeen-styleguidist-and-storybook)
* [Are there any other projects like this?](#are-there-any-other-projects-like-this)

<!-- tocstop -->

## How to use `ref`s in examples?

Use `ref` prop as a function and assign a reference to a local variable:

```jsx
initialState = { value: '' }
let textarea
;<div>
  <Button onClick={() => textarea.insertAtCursor('Pizza')}>
    Insert
  </Button>
  <Textarea
    value={state.value}
    onChange={e => setState({ value: e.target.value })}
    ref={ref => (textarea = ref)}
  />
</div>
```

## How to exclude some components from style guide?

Styleguidist will ignore tests (`__tests__` folder and file names containing `.test.js` or `.spec.js`) by default.

Use [ignore](Configuration.md#ignore) option to customize this behavior:

```javascript
module.exports = {
  ignore: ['**/*.spec.js', '**/components/Button.js']
}
```

> **Note:** You should pass glob patterns, for example, use `**/components/Button.js` instead of `components/Button.js`.

## How to hide some components in style guide but make them available in examples?

Enable [skipComponentsWithoutExample](Configuration.md#skipcomponentswithoutexample) option and do not add example file (`Readme.md` by default) to components you want to ignore.

Require these components in your examples:

```jsx
const Button = require('../common/Button')
;<Button>Push Me Tender</Button>
```

Or, if you want to make these components available for all examples:

```jsx
// styleguide.config.js
module.exports = {
  require: [path.resolve(__dirname, 'styleguide/setup.js')]
}

// styleguide/setup.js
import Button from './src/components/common/Button'
global.Button = Button
```

The `Button` component will be available in every example without a need to `require` it.

## How to set global styles for user components?

Using the [jss-global](https://github.com/cssinjs/jss-global) API you can set global styles in your config:

```javascript
module.exports = {
  components: 'src/components/**/[A-Z]*.js',
  styles: {
    StyleGuide: {
      '@global body': {
        fontFamily: 'Helvetica'
      }
    }
  }
}
```
<commit_msg>Doc: Add example using require.context (fixes #808) (#809)<commit_after># Cookbook

<!-- To update run: npx markdown-toc --maxdepth 2 -i docs/Cookbook.md -->

<!-- toc -->

* [How to use `ref`s in examples?](#how-to-use-refs-in-examples)
* [How to exclude some components from style guide?](#how-to-exclude-some-components-from-style-guide)
* [How to hide some components in style guide but make them available in examples?](#how-to-hide-some-components-in-style-guide-but-make-them-available-in-examples)
* [How to dynamically load other components in an example?](#how-to-dynamically-load-other-components-in-an-example)
* [How to set global styles for user components?](#how-to-set-global-styles-for-user-components)
* [How to add custom JavaScript and CSS or polyfills?](#how-to-add-custom-javascript-and-css-or-polyfills)
* [How to use React Styleguidist with Preact?](#how-to-use-react-styleguidist-with-preact)
* [How to change styles of a style guide?](#how-to-change-styles-of-a-style-guide)
* [How to change the layout of a style guide?](#how-to-change-the-layout-of-a-style-guide)
* [How to change style guide dev server logs output?](#how-to-change-style-guide-dev-server-logs-output)
* [How to debug my components and examples?](#how-to-debug-my-components-and-examples)
* [How to debug the exceptions thrown from my components?](#how-to-debug-the-exceptions-thrown-from-my-components)
* [How to use React's production or development build?](#how-to-use-reacts-production-or-development-build)
* [Why does the style guide list one of my prop types as `unknown`?](#why-does-the-style-guide-list-one-of-my-prop-types-as-unknown)
* [Why object references don’t work in example component state?](#why-object-references-dont-work-in-example-component-state)
* [How to use Vagrant with Styleguidist?](#how-to-use-vagrant-with-styleguidist)
* [How to add external JavaScript and CSS files?](#how-to-add-external-javascript-and-css-files)
* [How to reuse project’s webpack config?](#how-to-reuse-projects-webpack-config)
* [How to use React Styleguidist with Redux, Relay or Styled Components?](#how-to-use-react-styleguidist-with-redux-relay-or-styled-components)
* [What’s the difference betweeen Styleguidist and Storybook](#whats-the-difference-betweeen-styleguidist-and-storybook)
* [Are there any other projects like this?](#are-there-any-other-projects-like-this)

<!-- tocstop -->

## How to use `ref`s in examples?

Use `ref` prop as a function and assign a reference to a local variable:

```jsx
initialState = { value: '' }
let textarea
;<div>
  <Button onClick={() => textarea.insertAtCursor('Pizza')}>
    Insert
  </Button>
  <Textarea
    value={state.value}
    onChange={e => setState({ value: e.target.value })}
    ref={ref => (textarea = ref)}
  />
</div>
```

## How to exclude some components from style guide?

Styleguidist will ignore tests (`__tests__` folder and file names containing `.test.js` or `.spec.js`) by default.

Use [ignore](Configuration.md#ignore) option to customize this behavior:

```javascript
module.exports = {
  ignore: ['**/*.spec.js', '**/components/Button.js']
}
```

> **Note:** You should pass glob patterns, for example, use `**/components/Button.js` instead of `components/Button.js`.

## How to hide some components in style guide but make them available in examples?

Enable [skipComponentsWithoutExample](Configuration.md#skipcomponentswithoutexample) option and do not add example file (`Readme.md` by default) to components you want to ignore.

Require these components in your examples:

```jsx
const Button = require('../common/Button')
;<Button>Push Me Tender</Button>
```

Or, if you want to make these components available for all examples:

```jsx
// styleguide.config.js
module.exports = {
  require: [path.resolve(__dirname, 'styleguide/setup.js')]
}

// styleguide/setup.js
import Button from './src/components/common/Button'
global.Button = Button
```

The `Button` component will be available in every example without a need to `require` it.

## How to dynamically load other components in an example?

Although examples don't have direct access to webpack's `require.context` feature, you *can* use it in a separate helper file which you require in your example code. If you wanted to create an example to load and show all of your icon components, you could do this:

```jsx
// load-icons.js
const iconsContext = require.context('./icons/', true, /js$/);
const icons = Object.keys(iconsContext).reduce( (icons, file) => {
	const Icon = iconsContext(file).default;
	const label = file.slice(2, -3); // strip './' and '.js'
	icons[label] = Icon;
	return icons;
}, {});

export default icons;

// IconGallery.md
const icons = require('./load-icons').default;

const iconElements = Object.keys(icons).map(iconName => {
  const Icon = icons[iconName];
  return <span key={iconName}>{iconName}: {<Icon />}</span>;
});

<div>{iconElements}</div>
```

## How to set global styles for user components?

Using the [jss-global](https://github.com/cssinjs/jss-global) API you can set global styles in your config:

```javascript
module.exports = {
  components: 'src/components/**/[A-Z]*.js',
  styles: {
    StyleGuide: {
      '@global body': {
        fontFamily: 'Helvetica'
      }
    }
  }
}
```

{'fraction_non_alphanumeric': 0.14528560870024285, 'fraction_numerical': 0.0010558547143912998, 'mean_word_length': 4.459365994236311, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 38, 'https://': 2, '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': '1825114', 'n_tokens_mistral': 3063, 'n_tokens_neox': 2958, 'n_words': 888}