A next-generation tool to create blazing-fast documentation sites
API
created:11/26/2020
,
updated:12/28/2020

Gatsby as a static site generator

The starting sample project was cloned from

tw-sb-rtl-starter

The final project can be found here:

source code

live site

Install gatsby

yarn add gatsby @component-controls/gatsby-theme-stories -D

component-controls has two configuration files - one is used during build-time in a nodejs environment, the other is used during run-time in a browser environment.

The rough equivalents of Storybook for those two configuration files are main.js and preview.(js|ts)

Update configuration

You can keep the main.js Storybook configuration file and rename preview.ts to runtime.tsx:

.storybook/main.js

module.exports = {
stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
// remove all storybook addons
};

.storybook/runtime.tsx

import '../src/tailwind.output.css';
// remove all addParameters and leave just the tailwind css import

Configuration file path

By default, the Storybook configuration file is kept in a folder name .storybook, while component-controls uses a .config folder. We will configure the gatsby stories theme in gatsby-config.js.

gatsby-config.js

module.exports = {
plugins: [
{
resolve: '@component-controls/gatsby-theme-stories',
options: {
configPath: '.storybook',
},
},
],
};

Launch scripts

Next, you should add the gatsby develop and gatsby build scripts to the project's package.json

package.json

"scripts": {
...
"tailwind:watch": "postcss ./src/styles/tailwind.css -o ./src/tailwind.output.css --watch",
"docs:build": "gatsby build",
"docs:start": "gatsby develop -p 6006",
"lint": "eslint \"./src/**/*.{ts,tsx,js,jsx}\"",
...
},

At his point, you can start your documentation site

yarn docs:start

And a new documentation site should be up and running

gatsby documentation sitegatsby site

Configure documentation site

You can configure the name, site and various other site parameters for the new documentation site

.storybook/main.js

module.exports = {
stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
siteUrl: 'https://tailwind-gatsby-controls-starter.netlify.app',
};

.storybook/runtime.tsx

import '../src/tailwind.output.css';
import { RunOnlyConfiguration } from '@component-controls/core';
const config: RunOnlyConfiguration = {
analytics: 'UA-XXXXXXXXX-X',
title: `Tailwind component-controls`,
description: `Tailwind project with typescript, react testing library and component-controls`,
author: `@component-controls`,
};
export default config;

Add testing page

component-controls allows adding fully customizable documentation pages to your site and comes with package of pre-configured pages.

.storybook/main.js

const { defaultBuildConfig } = require('@component-controls/core');
module.exports = {
stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
siteUrl: 'https://tailwind-gatsby-controls-starter.netlify.app',
pages: {
story: {
tabs: {
...defaultBuildConfig.pages.story.tabs,
test: '@component-controls/pages/TestingPage',
},
},
},
};

The new Testing Page should now be visible

testing pagetesting page

Add jest snapshot tests

The @component-controls/jest-snapshots package is automatically creating jest snapshot tests from your existing stories. It has an easy to use command-line interface that we will use in this example but also offers a fully customizable API.

Install the jest-snapshots package

yarn add @component-controls/jest-snapshots -D

Configure test script

We will launch the cc-jest command-line with the -c parameter pointing to the folder storing your configuration files. You can also add other parameters such as --coverage.

package.json

{
"name": "tailwind-storybook-controls",
...
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "cc-jest -c .storybook",
"eject": "react-scripts eject",
...
},
...
}

Run the tests

yarn test

Running the jest-snapshots test will execute any existing tests (ie src/lib/components/button/button.spec.tsx) as well as snapshot tests automatically created for all your stories.

After running the tests, you should have a file tests/__snapshots__/stories.test.js.snap, with snapshots like this one:

tests/__snapshots__/stories.test.js.snap

exports[`Components/Button Primary 1`] = `
<DocumentFragment>
<button
class="rounded-md focus:outline-none focus:shadow-outline bg-primary-500 text-white hover:bg-primary-600 py-4 px-8"
type="button"
>
Button Label
</button>
</DocumentFragment>
`;