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.
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
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
Add nextjs
and react packages:
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.
All you have to do is add Nextjs as a dependency:
yarn add next
Then follow the steps for existing Nextjs projects.
yarn add @component-controls/nextjs-plugin
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({ configPath: '.config', ....other options });
mkdir pages
Create a new or edit index.tsx
or index.js
file in the pages folder:
view source...
pages/index.tsx
import React, { FC } from 'react';import { GetStaticProps } from 'next';import { DocType, defDocType } from '@component-controls/core';import { DocPage } from '@component-controls/app';import { Layout, store, getIndexPage } from '@component-controls/nextjs-plugin';interface PageListProps {type: DocType;docId?: string;storyId?: string;}const HomePage: FC<PageListProps> = ({ type = defDocType, docId, storyId }) => {return (<Layout docId={docId} storyId={storyId}><DocPage type={type} /></Layout>);};export const getStaticProps: GetStaticProps = async () => {const homePage = getIndexPage(store);const { docId = null, type = null, storyId = null } = homePage;return { props: { docId, type, storyId } };};export default HomePage;
Create a new [doctype].tsx
or [doctype].js
file in the pages folder:
view source...
pages/[doctype].tsx
import React, { FC } from 'react';import { GetStaticProps, GetStaticPaths } from 'next';import { DocType, defDocType } from '@component-controls/core';import { DocumentHomePage } from '@component-controls/app';import {Layout,store,getHomePagesPaths,getDocHomePage,} from '@component-controls/nextjs-plugin';interface PageListProps {type: DocType;docId?: string;storyId?: string;}const DocHomeTemplate: FC<PageListProps> = ({type = defDocType,docId,storyId,}) => {return (<Layout docId={docId} storyId={storyId}><DocumentHomePage type={type} /></Layout>);};export const getStaticPaths: GetStaticPaths = async () => {return { paths: getHomePagesPaths(store), fallback: false };};export const getStaticProps: GetStaticProps = async ({ params }) => {const { doctype: basepath } = params as { doctype: string };const page = getDocHomePage(store, basepath);const { type = null, docId = null, storyId = null } = page || {};return { props: { docId, storyId, type } };};export default DocHomeTemplate;
Create a new sub-folder [doctype]
in the pages folder, and in it a new [...docid].tsx
or [...docid].js
file:
mkdir pages/[doctype]
view source...
pages/[doctype]/[...docid].tsx
import React, { FC } from 'react';import { GetStaticProps, GetStaticPaths } from 'next';import { DocPage } from '@component-controls/app';import { DocType } from '@component-controls/core';import {Layout,store,getDocPagesPaths,getDocPage,} from '@component-controls/nextjs-plugin';interface DocPageProps {docId?: string;storyId?: string;type: DocType;activeTab?: string;category?: string;}const DocPageTemplate: FC<DocPageProps> = ({docId,storyId,type,category,activeTab,}) => {return (<Layout docId={docId} storyId={storyId} activeTab={activeTab}><DocPage type={type} category={category} /></Layout>);};export const getStaticPaths: GetStaticPaths = async () => {return { paths: getDocPagesPaths(store), fallback: false };};export const getStaticProps: GetStaticProps = async ({ params }) => {const { doctype, docid } = params as { doctype: string; docid: string[] };const page = getDocPage(store, doctype, docid);const {type = null,docId = null,storyId = null,category = null,activeTab = null,} = page || {};return { props: { docId, type, storyId, category, activeTab } };};export default DocPageTemplate;
Check our create a documentation site tutorial