Styleguidist Goodies

Description

A set of goodies to help you configure react-styleguidist. styleguidist-goodies provides a custom guideConfig function which accepts all the styleguide config params and defines a set of defaults for some of them.

Installation

1. Install styleguidist

This library is meant to be used with react-styleguidist so install it first. You can find the full React-Styleguidist's "Getting started" instructions here, however, if you use styleguidist-goodies to configure styleguidist you only have to follow this steps:

Install the dependencies

npm install --save-dev react-styleguidist react react-dom webpack

Add these scripts to the `package.json`:

{
  // ...
  "scripts": {
    "styleguide-server": "styleguidist server",
    "styleguide-build": "styleguidist build"
  }
}

2. Install styleguidist-goodies

npm install --save-dev styleguidist-goodies

Usage

Add a styleguide.config.js file to the project´s root folder.

var { guideConfig } = require("styleguidist-goodies");
var path = require("path");
var webpackConfig = require("./webpack-config");

module.exports = guideConfig({
  src: "./src/components",

  title: "Style guide",

  outputDir: "./styleguide",

  host: "0.0.0.0",

  port: 3032,

  exampleWrapper: path.join(__dirname, "src", "styleguide", "example-wrapper"),

  webpackConfig: webpackConfig,
});

Config params

Styleguidist-goodies honors the styliguidist config params changing some defaults and providing some goodies:

Param	Type	Required?	Description	Default value
components	String	function	✓	Components glob expression or function
sections	Array			See sections
sectionsPath	String			See sections
styleguideDir	String		Path to the generated style guide.	`./guide`
serverHost	String		Host used by the styleguidist server.	`0.0.0.0`
serverPort	Number		Port used by the styleguidist server.	`3032`
highlightTheme	String		CodeMirror theme name to use for syntax highlighting in examples	`base16-light`
getExampleFilename	Function		Function that returns examples file path for a given component path.	See `getExampleFilename`
getComponentPathLine	Function		Function that returns a component path line (name displayed under the component name).	See `getComponentPathLine`
updateWebpackConfig	Function		Function that allows you to modify Webpack config used by styleguidist.	See `updateWebpackConfig`
formatImport	function	✓*	Callback used to generate the import declaration.	See `formatImport`
exampleWrapper	String		Path to a module that defines a React component which will be used as a wrapper in the examples.

sections

Section configuration with react-styleguidist requires a precise definition of each section and its components. However, Styleguidist-goodies allows section definition by file structure conventions.

Configuring sections using plain react-styleguidist:

module.exports = {
  // ...
  sections: [
    {
      name: 'Buttons',
      content: 'src/components/buttons/index.md',
      components: 'src/components/buttons/*.js',
    },
  ],
};

With Styleguidist-goodies, you can specify a sectionPath parameter and this section structure will be defined implicitly through the file structure:

project
│
└───src
|   └───components
|   |   └───buttons
│   |   |   └───_guide
│   |   |   |     index.md
│   |   |   |     button-primary.md
│   |   |   |     button-secondary.md
│   |   |   |     ...

Styleguidist-goodies shows sections and their components alphabetically by default, however it can be overrided using a config.json file.

_guide/config.json

{
  "position": 1,
  "components": "./*.js",
  "componentsOrder": ["button", "button-primary", "button-secondary"],
  "sections": [
    {
      "name": "button-components",
      "content": "/_guide/button-components.md",
      "components": "/button-components/**/*.js"
    }
  ]
}

Param	Type	Description	Default value
position	Integer	Section's position in the style guide, ascending order	Alphabetic
components	String	The list of components	`"*/.js"`
componentsOrder	Array	Components' order inside the section. Components are referenced by their file names without extension	Alphabetic
sections	Array	List of subsections	`[]`

getExampleFilename

This function returns the example file path for a given component path. By defult, components files are fetched up in project/{components path}/{component path}/_guide/{component name}.md.

const defaultGetExampleFilename = componentPath => {
  const name = path.basename(componentPath, ".js");

  if (name === "index") {
    return null;
  }

  const dir = path.dirname(componentPath);
  return path.join(dir, "_guide", `${name}.md`);
};

getComponentPathLine

This function returns the component path line (name displayed under the component name). By default, the function uses the formatImport function to build the component path. This formatter outputs ES2105 imports.

As result, instead of components/Buttons/Button.js it prints import Button from 'components/Button';

const defaultGetComponentPathLine = formatImport => componentPath => {
  const name = path.basename(componentPath, ".js");
  const dir = path.dirname(componentPath);

  return `import ${capitalize(name)} from "${formatImport(dir, name)}";`;
};

updateWebpackConfig

Function that allows you to further customize Webpack config for styleguidist.

To use the Styleguidist-goodies default updateWebpackConfig function, it´s necessary to define the webpackConfig param which must be your project webpack config.

The default function:

Fix a problem with node_modules inclusion
Copy all aseets in assetsDir in styleguideDir
Configure exampleWrapper alias

const defaultWebpackConfig = (webpackConfig, assetsDir, styleguideDir, exampleWrapper) => (config, env) => {

  const loaders = webpackConfig.module.loaders.map(loader => {
    // ugly, ugly, ugly trick to prevent react-styleguidist errors...
    if (!loader.include && !loader.exclude) {
      loader.include = "node_modules";
    }

    return loader;
  });

  config.module.loaders.push(...loaders);

  if (assetsDir) {
    config.plugins.push(new WebpackOnBuildPlugin(() => {
      try {
        fs.copySync(assetsDir, styleguideDir);
      } catch (err) {
        console.error(err);
      }
    }));
  }

  if (exampleWrapper) {
    config.resolve.alias["rsg-components/Wrapper"] = exampleWrapper;
  }

  return config;
};

formatImport

Callback which will be used to generate the component path line. This param is used only in the default getExampleFilename, so it´s required only if you delegate the getExampleFilename on Styleguidist-goodies.

formatImport example:

formatImport: function(componentDir, componentFile) {
  return componentDir.replace(/^src\//, "my-project\/") + "/" + componentFile;
}