styleguidist-goodies v2.0.0

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:

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"
    }
  ]
}

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;
}