Manual Installation

Learn how to integrate Docstra into an existing Next.js project.

Integrating Docstra into an existing Next.js project is straightforward. Follow these steps to get up and running.

Prerequisites

An existing Next.js project (Version 14 or later recommended).
Node.js 20 or later.
Tailwind CSS installed and configured.

Step 1: Install Dependencies

Install the docstra package using your preferred package manager:

Terminal
pnpm add docstra

Step 2: Create Configuration

Create a docstra.config.ts file in the root of your project. This file controls the behavior and appearance of your documentation.

docstra.config.ts
import { defineDocstraConfig } from 'docstra/mdx';
 
export default defineDocstraConfig({
    collections: {
        docs: 'content'
    },
    navbar: {
        logo: {
            link: '/',
            src: '/brand/logo.svg',
            alt: 'Docstra'
        },
        links: [{ name: 'Introduction', href: '/docs' }]
    }
});

For more information about the configuration, see Configuration.

Step 3: Setup Data Source

Create a lib/source.ts file to initialize the Docstra data source. This will handle loading your MDX files and generating the sidebar.

lib/source.ts
import { docs } from '@/.docstra/index';
import { createSource } from 'docstra/mdx';
 
export const source = createSource({
    source: docs,
    baseUrl: '/docs'
});

Step 4: Configure MDX Components

Define the components that will be used to render your MDX content in mdx-components.tsx.

mdx-components.tsx
import { defaultMdxComponents } from 'docstra/mdx';
import { DocstraCodeBlock } from 'docstra';
 
export function getMDXComponents() {
    return {
        ...defaultMdxComponents,
        code: DocstraCodeBlock
    };
}

Good to know: You can see our custom MDX Components for more information.

Step 5: Create the docs route

Create a docs route at app/docs/layout.tsx and app/docs/[[...slug]]/page.tsx.

Now add the following code to app/docs/layout.tsx:

app/docs/layout.tsx
import { source } from '@/lib/source';
import { DocstraLayout } from 'docstra';
 
export default async function Page({ children }: { children: React.ReactNode }) {
    return <DocstraLayout tree={source.getTree()}>{children}</DocstraLayout>;
}

Now add the following code to app/docs/[[...slug]]/page.tsx:

app/docs/[[...slug]]/page.tsx
import docstraConfig from '@/docstra.config';
import { DocstraBody, DocstraProvider } from 'docstra';
 
import { source } from '@/lib/source';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
 
export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
    const { slug } = await params;
 
    const page = source.getPage(slug);
 
    if (!page) return notFound();
 
    const MDX = source.getPageMdx(slug);
 
    return (
        <DocstraProvider docstraConfig={docstraConfig} page={page}>
            <DocstraBody>
                <MDX components={getMDXComponents()} />
            </DocstraBody>
        </DocstraProvider>
    );
}
 
export function generateStaticParams() {
    return source.generateStaticParams();
}
 
export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
    const { slug } = await params;
    const page = source.getPage(slug);
    if (!page) return notFound();
 
    return {
        title: page.metadata.title,
        description: page.metadata.description
    };
}

Step 6: Import Styles

Include Docstra's CSS in your app/globals.css file.

app/globals.css
@import 'tailwindcss';
@import 'docstra/css';
@plugin "@tailwindcss/typography";

Step 7: Add Content

Create your first documentation page at content/index.mdx:

content/01-index.mdx
---
title: My First Docstra Page
---
 
# Welcome!
 
I Love coding!

Visit /docs in your browser to see your documentation in action!

How is this guide?

Last updated on March 30, 2026

Deployment

Callout