avatarMartin Adams

Summary

The webpage provides a technical guide on integrating a Docusaurus documentation website into a Next.js application as a subroute, detailing the installation, configuration, and troubleshooting steps required for a successful implementation.

Abstract

The article outlines a project where Docusaurus is incorporated within a Next.js website, a task valued at $200. It begins with the installation of a Next.js project using pnpm dlx create-next-app@latest, followed by setting up Docusaurus within a subdirectory using pnpm dlx create-docusaurus@latest doc classic. The author explains the necessity to modify Docusaurus's build command to correctly place the built files within the Next.js public directory. After building both projects, the author encounters a 404 error when navigating to the Docusaurus route, which is resolved by configuring rewrites in next.config.mjs. The article concludes with a successful demonstration of the integrated sites and an invitation for feedback and connection on Twitter, along with a recommendation for an AI service.

Opinions

  • The author values the use of Docusaurus within a Next.js project for documentation purposes.
  • The employer's decision to combine Docusaurus with Next.js is seen as a valuable investment, indicating a preference for modern web development tools.
  • The author demonstrates a preference for using pnpm as the package manager.
  • The author encountered an issue with routing in Next.js, which was resolved by utilizing the rewrites option in next.config.mjs.
  • The author is open to engagement and feedback from readers, suggesting a collaborative mindset.
  • The author endorses an AI service, implying it as a cost-effective alternative to ChatGPT Plus (GPT-4).

How to add a Docusaurus website within Next.js Website as a route? It’s worth $200

I recently received a project worth $200.

The employer wants to use Docusaurus in a Next.js project.

Installation Next.js

pnpm dlx create-next-app@latest
What is your project named? next-docusaurus
Would you like to use TypeScript? No / Yes No
Would you like to use ESLint? No / Yes Yes
Would you like to use Tailwind CSS? No / Yes No
Would you like to use `src/` directory? No / Yes No
Would you like to use App Router? (recommended) No / Yes No
Would you like to customize the default import alias (@/*)? No / Yes Yes
What import alias would you like configured? @/*
pnpm install
pnpm build
pnpm dev
├── README.md
├── jsconfig.json
├── next.config.mjs
├── package.json
├── pages
│   ├── _app.js
│   ├── _document.js
│   ├── api
│   │   └── hello.js
│   └── index.js
├── pnpm-lock.yaml
├── public
│   ├── favicon.ico
│   ├── next.svg
│   └── vercel.svg
└── styles
    ├── Home.module.css
    └── globals.css

Installation Docusaurus

pnpm dlx create-docusaurus@latest doc classic
cd doc
pnpm install
pnpm start

We need to modify the build command of docusaurus.

"build": "docusaurus build && rm -rf '../public/doc' && mv 'build' '../public/doc'",
{
...
"scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build && rm -rf '../public/doc' && mv 'build' '../public/doc'",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
...
}

Build the docusaurus project.

pnpm build // build docusaurus ()
cd ..
pnpm build // build next.js

We visit http://localhost:3000/doc. But why is 404 displayed?

Next.js

Troubleshooting

README.md
├── doc
│   ├── README.md
│   ├── babel.config.js
│   ├── blog
│   │   ├── 2019-05-28-first-blog-post.md
│   │   ├── 2019-05-29-long-blog-post.md
│   │   ├── 2021-08-01-mdx-blog-post.mdx
│   │   ├── 2021-08-26-welcome
│   │   └── authors.yml
│   ├── docs
│   │   ├── intro.md
│   │   ├── tutorial-basics
│   │   └── tutorial-extras
│   ├── docusaurus.config.js
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── sidebars.js
│   ├── src
│   │   ├── components
│   │   ├── css
│   │   └── pages
│   └── static
│       └── img
├── jsconfig.json
├── next.config.mjs
├── package.json
├── pages
│   ├── _app.js
│   ├── _document.js
│   ├── api
│   │   └── hello.js
│   └── index.js
├── pnpm-lock.yaml
├── public
│   ├── doc
│   │   ├── 404.html
│   │   ├── assets
│   │   ├── blog
│   │   ├── docs
│   │   ├── img
│   │   ├── index.html
│   │   ├── markdown-page
│   │   └── sitemap.xml
│   ├── favicon.ico
│   ├── next.svg
│   └── vercel.svg
└── styles
    ├── Home.module.css
    └── globals.css

I found the override method in the Next.js documentation.

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  rewrites: async () => [
    {
      source: "/doc",
      destination: "/doc/index.html",
    },
  ],
};
export default nextConfig;

DONE

https://next-docusaurus-martinadamsdev.vercel.app/doc

Give Me Claps and Comments

Writing has always been my passion, and it gives me the pleasure of helping and inspiring people. If you have any questions, feel free to comment!

Welcome to Connect me on Twitter.

If you enjoyed this article, consider trying out the AI service I recommend. It provides the same performance and functions to ChatGPT Plus(GPT-4) but more cost-effective, at just $6/month (Special offer for $1/month). Click here to try ZAI.chat.

Docusaurus
Nextjs
React
Vercel
Upwork
Recommended from ReadMedium