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

> Deploy your Docusaurus site to Vercel or Netlify with ease. Follow this complete guide to import your Git repo, set the build command, and specify the output directory for a seamless deployment.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/package.json) includes the build script:

```json
{
  "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`](https://github.com/facebook/docusaurus/blob/main/netlify.toml):

```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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) matches Netlify's "Pretty URLs" setting:

```javascript
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`](https://github.com/facebook/docusaurus/blob/main/vercel.json) file for custom build and routing rules:

```json
{
  "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`](https://github.com/facebook/docusaurus/blob/main/netlify.toml) file for build settings and environment variables:

```toml
[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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) with your platform's URL handling preferences
- Use [`vercel.json`](https://github.com/facebook/docusaurus/blob/main/vercel.json) or [`netlify.toml`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/vercel.json) and [`netlify.toml`](https://github.com/facebook/docusaurus/blob/main/netlify.toml) files. Docusaurus automatically inlines environment variables prefixed with `DOCUSAURUS_` or other custom prefixes defined in your configuration during the static build generation.