React Styleguidist

Common errors

• Error: Webpack 4 is no longer supported.

  cause Your project is using `react-styleguidist` v12 or higher with Webpack 4.
  fix Upgrade Webpack to version 5: `npm install webpack@^5 webpack-cli@^4 --save-dev`.

• Error: You must install peer dependencies: react@>=18.0 react-dom@>=18.0

  cause Your project is running `react-styleguidist` v13.1.1 or higher with an older version of React or ReactDOM.
  fix Upgrade `react` and `react-dom` to version 18 or higher: `npm install react@^18.0.0 react-dom@^18.0.0`.

• Error: Cannot find module 'babel-loader' (or similar loader name)

  cause Your `styleguide.config.js` requires a specific Webpack loader (e.g., `babel-loader`), but it has not been installed as a dependency in your project.
  fix Install the missing loader as a development dependency: `npm install --save-dev babel-loader` (replace `babel-loader` with the actual missing loader).

• TypeError: Cannot read properties of undefined (reading 'build')

  cause Attempting to call `.build()` or `.server()` directly on `require('react-styleguidist')` without passing a configuration object to the factory function.
  fix Pass your configuration object to the `react-styleguidist` factory function to instantiate it correctly: `const styleguidist = require('react-styleguidist')(config); styleguidist.build(...);`

Warnings

• breaking React Styleguidist v13.0.0 dropped support for React 16. Projects using v13 or later must use React 17 or newer.
  Fix: Upgrade your project's `react` and `react-dom` dependencies to version `^17.0.0` or `^18.0.0`.
• breaking React Styleguidist v12.0.0 deprecated support for Webpack 4. If you are using v12 or higher, your project must use Webpack 5.
  Fix: Upgrade your project's `webpack` and `webpack-cli` dependencies to version `^5.0.0`.
• gotcha The `defaultProps` property on functional components is deprecated in modern React (v18+). While React Styleguidist v13.1.3 fixed an internal bug related to `defaultProps`, direct usage on functional components is discouraged.
  Fix: For functional components, migrate `defaultProps` to use default parameter values or destructuring with defaults directly in the function signature (e.g., `function Button({ children, onClick = () => {} })`).
• gotcha Incorrect Webpack configuration is a common source of issues, leading to compilation failures or components not rendering correctly within the style guide. React Styleguidist internally uses Webpack and allows extensive customization.
  Fix: Carefully review the 'Configuring Webpack' section in the official documentation. Ensure all necessary loaders (e.g., `babel-loader`, `css-loader`) and plugins are installed as dev dependencies and correctly configured in `styleguide.config.js`.

Install

• npm install react-styleguidist npm
• yarn add react-styleguidist yarn
• pnpm add react-styleguidist pnpm

Imports

• styleguidist
  wrong:

  import styleguidist from 'react-styleguidist';

  correct:

  const styleguidist = require('react-styleguidist');

  The primary programmatic API is a CommonJS default export factory function. ESM `import` is not commonly used or directly supported for the Node.js API without a transpilation step.
• styleguide.config.js (config export)
  wrong:

  export default { /* config */ };

  correct:

  module.exports = { /* config */ };

  Configuration files like `styleguide.config.js` typically use CommonJS `module.exports` for their configuration object. While ESM syntax might work in some environments with proper setup, `module.exports` is the idiomatic and most compatible approach.
• styleguidist(config).build
  wrong:

  import { build } from 'react-styleguidist';

  correct:

  const styleguidist = require('react-styleguidist')(config); styleguidist.build((err, conf) => { /* ... */ });

  The `build` method is available on the object returned by the `react-styleguidist` factory function, not as a direct named export from the package.

Quickstart

This quickstart sets up a basic `react-styleguidist` project. It includes `package.json` scripts, a `styleguide.config.js` with Babel for JSX support, a simple `Button` component, and its accompanying Markdown documentation.

{
  "name": "my-component-library",
  "version": "1.0.0",
  "scripts": {
    "styleguide": "styleguidist start",
    "styleguide:build": "styleguidist build"
  },
  "dependencies": {
    "react": ">=18.0",
    "react-dom": ">=18.0"
  },
  "devDependencies": {
    "react-styleguidist": "^13.1.4",
    "babel-loader": "^9.0.0",
    "@babel/core": "^7.0.0",
    "@babel/preset-env": "^7.0.0",
    "@babel/preset-react": "^7.0.0"
  }
}

// styleguide.config.js
module.exports = {
  components: 'src/components/**/*.jsx',
  webpackConfig: {
    module: {
      rules: [
        {
          test: /\.jsx?$/,
          exclude: /node_modules/,
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env', '@babel/preset-react']
          }
        }
      ]
    }
  },
  title: 'My Component Library Style Guide'
};

// src/components/Button/Button.jsx
import React from 'react';
import PropTypes from 'prop-types';

function Button({ children, onClick = () => {} }) {
  return (
    <button
      style={{
        padding: '10px 20px',
        border: 'none',
        borderRadius: '5px',
        backgroundColor: '#2D9EE0',
        color: 'white',
        cursor: 'pointer',
      }}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

Button.propTypes = {
  /**
   * Button content
   */
  children: PropTypes.node.isRequired,
  /**
   * Click handler
   */
  onClick: PropTypes.func,
};

export default Button;

// src/components/Button/Button.md
```## Button

A versatile button component.

### Usage

```jsx
<Button onClick={() => alert('Clicked!')}>Click Me</Button>
```

```jsx
<Button>Another Button</Button>
```
```