A next-generation tool to create blazing-fast documentation sites
API
created:11/26/2020
updated:4/4/2021

Nextjs 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 nextjs

yarn add next emotion@10.0.27 emotion-server@10.0.27 @emotion/core@10.1.1 @component-controls/nextjs-plugin -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

// empty file

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 nextjs plugin in next.config.js.

next.config.js

const withStories = require('@component-controls/nextjs-plugin/build');
module.exports = withStories({
future: {
webpack5: true, //use webpack 5 for nextjs
},
configPath: '.storybook',
});

Create page templates

The component-controls nextjs plugin needs to be set up with page templates in a pages folder of your project

mkdir pages

You can either copy the pages from this github repo or follow the getting started with nextjs tutorial.

Inject tailwind css

pages/_app.js

import React from 'react';
import NextApp from 'next/app';
import '../src/tailwind.output.css';
export default class App extends NextApp {
render() {
const { Component, pageProps } = this.props;
return <Component {...pageProps} />;
}
}

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": "next build && next export",
"docs:start": "next -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 { 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/cc-cli 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 cc-cli package

yarn add @component-controls/cc-cli -D

Configure test:create script

We will launch the cc-cli command-line tool to create automatically tests for all our existing stories.

package.json

{
"name": "tailwind-storybook-controls",
...
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test:create": "cc-cli -c ./.config -o tests -t stories.test.ts -n components -f ts",
"test": "yarn jest"
"eject": "react-scripts eject",
...
},
...
}

Run the tests

yarn test

Running the test:create script test will a tests file stories.test.ts (typecript format) in the tests folder.

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