How to Deploy a Docusaurus Site to Vercel or Netlify: A Complete Guide

Deploy a Docusaurus site to Vercel or Netlify by importing your Git repository, setting the build command to npm run build, and specifying build as the output directory.

Deploying a Docusaurus site to Vercel or Netlify leverages the static-site output generated by the docusaurus build command. According to the official Docusaurus documentation in website/versioned_docs/version-3.9.2/deployment.mdx, both Jamstack platforms can automatically build and host your documentation site directly from a Git repository with minimal configuration.

Prerequisites

Before deploying to Vercel or Netlify, ensure your project meets these requirements:

• A Docusaurus project with a package.json file containing a build script
• Your code pushed to a Git repository (GitHub, GitLab, or Bitbucket)
• Node.js version compatibility as specified in your project documentation

Connecting Your Repository

Both platforms follow a similar import flow to connect your Docusaurus repository.

Vercel Import Process

In website/versioned_docs/version-3.9.2/deployment.mdx lines 215-219, the documentation specifies that you should use Vercel's Import Git flow. Navigate to the Vercel dashboard, click "Add New Project," and select your Git provider. Vercel automatically detects the framework settings, though you should verify the build configuration in the next step.

Netlify Import Process

For Netlify, use the New site from Git wizard as documented in deployment.mdx lines 155-169. In the Netlify dashboard, select "Add new site" and choose your Git repository. Netlify attempts to auto-detect build settings, but manual configuration ensures compatibility with Docusaurus's output structure.

Configuring Build Settings

The build configuration is identical for both Vercel and Netlify according to deployment.mdx lines 150-152.

Build Command and Output Directory

Set the following values in your platform's build configuration:

• Build command: npm run build (or yarn build)
• Output directory: build

These settings tell the platform to execute the Docusaurus build script and deploy the static files generated in the build folder.

Package.json Scripts

Ensure your package.json includes the build script:

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "serve": "docusaurus serve"
  }
}

Handling Monorepo Configurations

If your Docusaurus site lives in a subdirectory like website/, you must configure the base directory settings.

Base Directory Settings

As noted in deployment.mdx lines 125-126, set the Root Directory (Vercel) or Base directory (Netlify) to website. This ensures the platform runs the build from the correct location and properly detects changes to your documentation files.

Custom Ignore Commands for Netlify

When using a monorepo structure with Netlify, you may need a custom ignore command to prevent unnecessary builds. According to deployment.mdx lines 190-191, add this to your netlify.toml:

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF website/"

This command tells Netlify to skip the build if only files outside the website/ directory changed.

Configuring URL Handling and Trailing Slashes

Docusaurus's trailingSlash configuration must align with your hosting platform's URL handling to prevent 404 errors.

Matching Trailing Slash Settings

As documented in deployment.mdx lines 203-208, ensure your docusaurus.config.js matches Netlify's "Pretty URLs" setting:

module.exports = {
  trailingSlash: false, // Set to true if Netlify's Pretty URLs is enabled
};

If you enable Netlify's Pretty URLs feature, set trailingSlash: true in your Docusaurus configuration. For Vercel, the default settings typically work without modification, but explicit configuration ensures consistent behavior across environments.

Optional Configuration Files

For advanced use cases, you can provide platform-specific configuration files at your repository root.

Vercel Configuration (vercel.json)

Create a vercel.json file for custom build and routing rules:

{
  "builds": [
    {
      "src": "website/package.json",
      "use": "@vercel/static-build",
      "config": { "distDir": "website/build" }
    }
  ],
  "routes": [{ "src": "/(.*)", "dest": "/website/build/$1" }]
}

Netlify Configuration (netlify.toml)

Create a netlify.toml file for build settings and environment variables:

[build]
  command = "npm run build"
  publish = "website/build"

[dev]
  command = "npm run start"
  targetPort = 3000

Summary

Deploying a Docusaurus site to Vercel or Netlify requires minimal configuration thanks to the static-site architecture of Docusaurus. Key takeaways include:

• Set the build command to npm run build and output directory to build on both platforms
• Configure the base directory to website if your project uses a monorepo structure
• Align the trailingSlash setting in docusaurus.config.js with your platform's URL handling preferences
• Use vercel.json or netlify.toml for advanced configuration and monorepo ignore commands

Frequently Asked Questions

Do Vercel and Netlify support Docusaurus deploy previews for pull requests?

Yes, both Vercel and Netlify automatically generate deploy previews for every pull request. As noted in website/versioned_docs/version-3.9.2/deployment.mdx lines 126-127, these preview URLs allow stakeholders to review documentation changes before merging to production, which aligns perfectly with documentation review workflows.

What should I do if my Docusaurus site is in a subdirectory like website/?

You must set the Root Directory (Vercel) or Base directory (Netlify) to website during project configuration. According to deployment.mdx lines 125-126, this ensures the build command runs from the correct location. For Netlify monorepos, you may also need a custom ignore command to prevent builds when only root-level files change.

How do I fix 404 errors on page refresh with Netlify or Vercel?

404 errors on refresh typically indicate a mismatch between the trailingSlash configuration in docusaurus.config.js and the platform's URL handling. As documented in deployment.mdx lines 203-208, set trailingSlash: true if you enable Netlify's "Pretty URLs" feature, or trailingSlash: false if you disable it. Both platforms serve the static build directory correctly when these settings align.

Can I use environment variables in my Docusaurus build on these platforms?

Yes, both Vercel and Netlify support environment variables that Docusaurus can access during the build process. You can configure these in the platform dashboards or via vercel.json and netlify.toml files. Docusaurus automatically inlines environment variables prefixed with DOCUSAURUS_ or other custom prefixes defined in your configuration during the static build generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}