How to Build Modern Docs Sites with Nextra and Vercel (Step-by-Step)

If you need to launch a sleek, high-performing documentation website quickly, Nextra Docs is a top choice—especially when paired with Vercel for seamless deployment. In this guide, you'll learn how to set up a Nextra Docs site from scratch, optimize it for your team, and deploy it live for free with Vercel. Whether you’re an API developer, backend engineer, or technical lead, you’ll see why Nextra is gaining traction for technical documentation.

💡 Looking for an API testing tool that generates beautiful API Documentation? Want an all-in-one platform where your developer team can collaborate with maximum productivity? Try Apidog—it streamlines workflow and replaces Postman at a much more affordable price!

What is Nextra Docs? A Modern Solution for Technical Documentation

Nextra Docs is a framework built on Next.js, designed to make documentation sites fast, flexible, and easy to maintain. Its key benefits:

• Markdown & MDX Friendly: Write docs using Markdown or MDX for interactive content.
• Out-of-the-Box Features: Automatic sidebar navigation, instant search, and responsive layouts.
• Next.js Integration: Leverages the speed, app router, and deployment power of Next.js.
• Customizable: Adjust themes, inject React components, or create custom layouts.
• Open Source: Supported by a growing community (3.8K+ GitHub stars).

Many developers appreciate Nextra’s “zero-config” polish and rapid Vercel deployment. Let’s see how you can put it into action.

Why Choose Nextra Docs with Vercel?

For API teams and engineering leaders, Nextra Docs on Vercel offers:

• Instant Deployment: Vercel detects Nextra/Next.js projects for one-click deploys.
• Fast Global Performance: Static site generation and CDN ensure lightning-fast load times.
• Free Hosting: Vercel’s free tier is robust enough for most projects, with custom domains available.
• Effortless Scaling: Handles spikes in traffic reliably.

In testing, a basic Nextra Docs site can be live on Vercel in under 5 minutes.

Step-by-Step: Setting Up a Nextra Docs Site with Vercel

Follow these steps to get your documentation site running locally and online.

1. Create a New Next.js Project

Open your terminal and run:

npx create-next-app my-nextra-docs

• Accept all prompts except:
  • “Would you like to customize the import alias?” (choose No or your preference).
  • “Would you like your code inside a src/ directory?” (choose No for simplicity, or Yes if you prefer).

Navigate to your project directory:

cd my-nextra-docs

2. Install Nextra Docs Dependencies

Install the essentials:

npm install next react react-dom nextra nextra-theme-docs

3. Update package.json Scripts

Make sure your package.json includes:

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

For faster development, try:

"dev": "next --turbopack"

Test your setup:

npm run dev

Visit http://localhost:3000 to confirm your app is running.

4. Configure Nextra Docs

Rename next.config.ts to next.config.mjs and update its content:

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

If you see a tsconfig.json error, add "next.config.mjs" to the include array:

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. Set Up MDX Components

Create mdx-components.js in your project root:

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. Update the App Layout

Replace the contents of app/layout.tsx (or src/app/layout.tsx if you chose src/):

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'

export const metadata = {
  // Add your metadata here
}

const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // Additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head>{/* Additional head tags here */}</Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Add Your First Documentation Page

Delete app/page.tsx (or src/app/page.tsx). This temporarily triggers a 404, which you’ll resolve next.

Create a resources folder in app (or src/app):

/app/resources
  /page.mdx

Add sample content to app/resources/page.mdx:

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favorite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Command Line](https://github.co./jlevy/the-art-of-command-line)

Or keep it simple:

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site :)

- Easy Markdown editing
- Automatic navigation
- Search and Table of Contents built-in

The redirect in next.config.mjs will now route / to /resources. Refresh http://localhost:3000 to see your Nextra Docs homepage.

Feel free to edit, add more pages, and explore features like dark/light mode.

Deploying Your Nextra Docs Site to Vercel

Ready to go live? Here’s how to deploy your site in minutes.

8. Push Your Code to GitHub

Initialize a git repository and push:

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Create your repository on GitHub first and replace yourusername/your-repo accordingly.

9. Deploy to Vercel

1. Visit vercel.com, log in or sign up.
2. Click New Project and import your GitHub repo.
3. Vercel auto-detects your Next.js/Nextra setup.
4. Click Deploy.

In just a few minutes, your docs will be live (e.g., https://my-nextra-docs.vercel.app).

Customizing Your Documentation Site

Make your docs fit your brand and workflow:

• Add Pages: Drop more .mdx files into /app or subfolders (e.g., /resources).
• Theme Customization: Adjust colors, fonts, and sidebar structure in theme.config.js (see Nextra docs).
• Custom Components: Extend mdx-components.js or add a /components directory for reusable React components.
• Search: Integrate Algolia in theme.config.js for comprehensive search.
• Live Code Blocks: Use tools like Sandpack or react-live for interactive code samples.

A callout component or custom design tweaks can make your documentation stand out and improve developer experience.

Troubleshooting Nextra Docs: Common Issues and Tips

• 404 Error after setup: Ensure your redirect in next.config.mjs targets /resources.
• TypeScript Errors: Confirm tsconfig.json includes next.config.mjs.
• Vercel Deploy Fails: Double-check package.json scripts and try clearing Vercel’s cache.
• App Router Confusion: Nextra Docs v4+ uses the Next.js App Router; earlier versions use the Pages Router.
• Need Examples?: Clone the Nextra repo or browse nextra.site.
• Speed Up Local Dev: Use Turbopack with next --turbopack.

Why Nextra Docs + Vercel Is a Winning Combo for API Teams

Nextra Docs delivers a streamlined, Markdown-first approach that’s perfect for developer teams and technical leads who value speed, clarity, and easy collaboration. Vercel’s hosting and deployment workflow make updates and scaling trivial—no server management needed.

Compared to alternatives like Docusaurus, Nextra Docs feels lighter and more modern, especially for API or product documentation. If you want to boost your team’s productivity, pair Nextra’s flexibility with tools like Apidog for robust API documentation and testing workflows.

Ready to launch? Build your Nextra Docs site, deploy to Vercel, and empower your team with clear, accessible documentation.

💡 Need an API platform that generates beautiful API Documentation? Looking for an integrated, all-in-one workspace for your developer team to achieve maximum productivity? Apidog covers all your needs and offers a more affordable alternative to Postman!