How to Use Nextra Docs and Deploy It to Vercel: A Step-by-Step Guide

If you want to create a sleek, modern documentation website with ease, Nextra Docs is one of the best tools available. Built on top of Next.js, Nextra lets you write your documentation in Markdown or MDX, customize the look and feel, and deploy it effortlessly—especially on Vercel. In this article, we’ll walk through how to set up a Nextra Docs site from scratch and deploy it to Vercel for free.

💡

Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demands, and replaces Postman at a much more affordable price!

button

What Are Nextra Docs? Your Doc-Building BFF

Nextra docs is a Next.js-based framework that makes creating documentation sites a breeze. It’s all about Markdown (or MDX) content with a pre-built Docs Theme that packs navigation, search, and a table of contents out of the box. Here’s why nextra docs rocks:

Markdown Simplicity: Write docs in Markdown or MDX for rich, interactive content.
Docs Theme Goodies: Auto-generated sidebar, search bar, and responsive layouts.
Next.js Power: Leverages Next.js’s speed, app router, and Vercel integration.
Customizable: Tweak themes, add React components, or build custom layouts.
Open-Source: With 3.8K+ GitHub stars, it’s community-driven and free.

Users rave about nextra docs for its “zero-config polish” and Vercel deploys. Ready to build your site? Let’s dive in!

Why Use Nextra Docs with Vercel?

Nextra docs is perfect for devs, startups, or open-source projects needing pro-level documentation fast. Pairing it with Vercel—Next.js’s home turf—means:

Seamless Deployment: Vercel auto-detects nextra docs for one-click deploys.
Blazing Speed: Static site generation and CDN for instant page loads.
Free Hosting: Vercel’s free tier handles most projects with custom domains.
Scalability: Handles traffic spikes without a hitch.

I deployed a test site to Vercel, and it was live in under 5 minutes—smooth as butter!

How to Set Up Nextra Docs: Step-by-Step Guide

Let’s create a nextra docs site from scratch using Next.js’s app router. Follow along, and you’ll have a local site running in ~20 minutes!

1. Create a New Next.js Project

Open your terminal and create a Next.js app:

npx create-next-app my-nextra-docs

During setup, select Yes for all prompts except:
“Would you like to customize the import alias (@/* by default)?” (choose No or your preference).
“Would you like your code inside a src/ directory?” (choose No or Yes—I recommend picking No for simplicity).
Navigate to the project folder:

cd my-nextra-docs

2. Install Nextra Docs Dependencies

Install the core packages for nextra docs:

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

3. Update package.json Scripts

Ensure package.json includes these scripts (they’re usually added by create-next-app):

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

For faster dev mode, you can add Turbopack (optional):

"dev": "next --turbopack"

Test the setup:

npm run dev

Visit http://localhost:3000 to confirm the Next.js app works.

Ugly:( But well, it works! Now let's try and fix this.

4. Configure Nextra Docs

Rename next.config.ts to next.config.mjs and replace its content with:

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 get a tsconfig.json error, your IDE (e.g., VS Code) may prompt to auto-fix it. If not, open tsconfig.json and 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 the 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 content 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 = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Add Documentation Pages

Delete app/page.tsx (or src/app/page.tsx). This makes our app throw a 404-error in our home page. Not to worry we got this!

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

/app/resources
  /page.mdx

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

For testing purposes, I added:

# Resources

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 favourite 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 Comand Line](https://github.co./jlevy/the-art-of-command-line)

But the content does not need to be complex and can be as simple as:

# Getting Started

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

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in

The redirect in next.config.mjs fixes the 404-error by routing / to /resources. Simply refresh http://localhost:3000 to see your nextra docs homepage—how cool is that!

Go ahead - edit this page, add more pages, and try out all the features like dark/light mode. The power is in your hands, and the options are endless!

Deploying Nextra Docs to Vercel

Now, let’s get your nextra docs site live on Vercel—super easy since Vercel’s built for Next.js.

8. Push Your Code to GitHub

Initialize a Git repo:

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 a new repo on GitHub first, replacing yourusername/your-repo with your details.

9. Deploy to Vercel

Go to vercel.com, sign up or log in.

Click New Project and import your GitHub repo.
Vercel auto-detects your nextra docs project (Next.js settings apply).
Click Deploy. In ~3 minutes, your site’s live at a URL like https://my-nextra-docs.vercel.app.
I deployed mine, and the custom domain setup was a breeze!

Customizing Your Nextra Docs Site

Want to make your nextra docs pop? Try these:

Add Pages: Drop more .mdx files in /app or subfolders like /resources.
Theme Tweaks: Update theme.config.js for colors, fonts, or sidebar options (see nextra.site/docs).
Custom Components: Extend mdx-components.js or create a /components folder.
Search Setup: Enable Algolia search via theme.config.js for full-text search.
Live Code: Add Sandpack or react-live for interactive code playgrounds.

I added a custom callout component to my docs—looked pro in 10 minutes!

Troubeshooting and Tips for Nextra Docs

404 error persists? Ensure the redirect in next.config.mjs points to /resources.
TS errors? Verify tsconfig.json includes next.config.mjs.
Vercel deploy fails? Check package.json scripts and clear Vercel’s cache.
App router confusion? Nextra docs 4+ uses Next.js app router; older versions support pages router.
Want examples? Clone the Nextra repo or check nextra.site.
Speed tip: Use Turbopack (next --turbopack) for faster local dev.

Why Nextra Docs and Vercel Are a Perfect Pair

Nextra docs makes documentation fun with its Markdown simplicity and Next.js speed. Vercel’s one-click deploys and free hosting seal the deal. Sure, the app router might trip up Next.js newbies, but the Nextra docs are solid. Compared to Docusaurus, nextra docs feels lighter and more modern.

Ready to launch your docs? Build your nextra docs site and deploy to Vercel—I’m stoked to see your creation! And definitely do check out Apidog.

💡

button