skip to main content
skip to navigation sidebar
skip to context sidebar
A next-generation tool to create blazing-fast documentation sites
API
Blog
Tutorial
Showcase
twitter
github
Edit this page
created:3/15/2021
updated:5/18/2021
nextjs

Nextjs

Below, we go over how to add a component-controls documentation site to new Nextjs projects, existing React projects, and existing Nextjs projects.
You can find a git repo and a live site.

Clone starter

The easiest way to get started is to clone the nextjs-controls-starter project
git clone https://github.com/ccontrols/nextjs-controls-starter my-nextjs-project

New project

If you want to create and configure a Nextjs documentation site from scratch instead of cloning the starter repo, the following steps are required:
mkdir my-nextjs-project && cd my-nextjs-project
Initialize the project:
yarn init -y
Add nextjs and react dependencies:
yarn add next react react-dom
Optional (but recommended), add typescript dependencies
yarn add --dev typescript @types/react @types/node

package.json

"scripts": {
    "build": "next build && next export",
    "start": "next",
    "start-server": "next build && next start"
  },
The remaining steps are the same as for existing Nextjs projects.

Existing (non-Nextjs) React project

All you have to do is add Nextjs as a dependency:
yarn add next
Then follow the steps for existing Nextjs projects.

Existing Nextjs project

Add component-controls

yarn add @component-controls/nextjs-plugin

Enable component-controls

The default options will configure component-controls to work with react apps, with react-docgen for prop-types and react-docgen-typescript for typescript props information

next.config.js

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

Create content pages

Create a pages folder

mkdir pages

Application home

Create a new or edit index.tsx or index.js file in the pages folder:
view source...

pages/index.tsx

import React from 'react';
import { GetStaticProps } from 'next';
import { NextLayout, getIndexPage } from '@component-controls/nextjs-plugin';
const HomePage: typeof NextLayout = props => <NextLayout {...props} />;
export const getStaticProps: GetStaticProps = async () => {
  return { props: getIndexPage() };
};
export default HomePage;

Document type home

Create a new [doctype].tsx or [doctype].js file in the pages folder:
view source...

pages/[doctype].tsx

import React from 'react';
import { GetStaticProps, GetStaticPaths } from 'next';
import {
  NextLayout,
  getHomePagesPaths,
  getDocHomePage,
} from '@component-controls/nextjs-plugin';
const DocHome: typeof NextLayout = props => <NextLayout {...props} />;
export const getStaticPaths: GetStaticPaths = async () => {
  return { paths: getHomePagesPaths(), fallback: false };
};
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { doctype: basepath } = params as { doctype: string };
  return { props: getDocHomePage(basepath) };
};
export default DocHome;

Document and Story pages

Create a new sub-folder [doctype] in the pages folder, and in it a new [...docid].tsx or [...docid].js file:

Create a pages folder

mkdir pages/[doctype]
view source...

pages/[doctype]/[...docid].tsx

import React from 'react';
import { GetStaticProps, GetStaticPaths } from 'next';
import {
  NextLayout,
  getDocPagesPaths,
  getDocPage,
} from '@component-controls/nextjs-plugin';
const DocPage: typeof NextLayout = props => <NextLayout {...props} />;
export const getStaticPaths: GetStaticPaths = async () => {
  return { paths: getDocPagesPaths(), fallback: false };
};
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { doctype, docid } = params as { doctype: string; docid: string[] };
  return { props: getDocPage(doctype, docid) };
};
export default DocPage;

Create your documentation site

Check our create a documentation site tutorial
Previous
Getting started/Site generators/Gatsby
Next
Getting started/Site generators/Webpack