Deploying Your VitePress Site

Build and deploy your VitePress site to popular hosting platforms

Deploying Your VitePress Site

VitePress generates static HTML files that can be deployed to any hosting platform. This guide covers building for production and deploying to popular platforms.

Prerequisites

These deployment guides assume:

• VitePress site is in the docs directory
• Using default build output directory (.vitepress/dist)
• VitePress installed as a local dependency
• npm scripts configured in package.json:

package.json

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Build and Test Locally

1. Build your site

   Generate static HTML for production:

   npm

   npm run docs:build
   

   Built files are output to .vitepress/dist.

2. Preview locally

   Test the production build before deploying:

   npm

   npm run docs:preview
   

   The preview server runs at http://localhost:4173.

3. Configure port (optional)

   Change the preview server port:

   package.json

   {
     "scripts": {
       "docs:preview": "vitepress preview docs --port 8080"
     }
   }
   

Setting a Public Base Path

If your site is served from a subdirectory, set the base option:

.vitepress/config.js

export default {
  base: '/blog/'  // For https://mywebsite.com/blog/
}

GitHub Pages example: Deploying to user.github.io/repo/ requires base: '/repo/'

HTTP Cache Headers

Optimize performance with proper cache headers for static assets.

Understanding Asset Hashing

VitePress uses content-based hashing for assets:

app.4f283b18.js
     ^^^^^^^^ content hash

The hash changes only when file content changes, enabling aggressive caching.

Recommended Cache Headers

For files in the assets/ directory:

Cache-Control: max-age=31536000,immutable

Netlify

Create docs/public/_headers:

_headers

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

The _headers file in the public directory is copied to the build output.

Netlify headers documentation

Vercel

Create vercel.json in your repository root:

vercel.json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Vercel headers documentation

Nginx

Add to your server block configuration:

location ~* ^/assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Platform-Specific Guides

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

These platforms work similarly - configure via dashboard:

1. Connect repository

   Link your Git repository to the platform.

2. Configure build settings

   • Build Command: npm run docs:build
   • Output Directory: docs/.vitepress/dist
   • Node Version: 20 (or above)
3. Deploy

   Push to your main branch to trigger deployment.

Don’t enable Auto Minify for HTML. It removes Vue-specific comments and causes hydration errors.

GitHub Pages

Deploy automatically using GitHub Actions:

1. Create workflow file

   Create .github/workflows/deploy.yml:

   .github/workflows/deploy.yml

   name: Deploy VitePress site to Pages
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   concurrency:
     group: pages
     cancel-in-progress: false
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v5
           with:
             fetch-depth: 0
         
         - name: Setup Node
           uses: actions/setup-node@v6
           with:
             node-version: 24
             cache: npm
         
         - name: Setup Pages
           uses: actions/configure-pages@v4
         
         - name: Install dependencies
           run: npm ci
         
         - name: Build with VitePress
           run: npm run docs:build
         
         - name: Upload artifact
           uses: actions/upload-pages-artifact@v3
           with:
             path: docs/.vitepress/dist
     
     deploy:
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       needs: build
       runs-on: ubuntu-latest
       name: Deploy
       steps:
         - name: Deploy to GitHub Pages
           id: deployment
           uses: actions/deploy-pages@v4
   
2. Configure Pages source

   In repository settings under Pages, set:

   • Source: GitHub Actions
3. Set base path

   Update .vitepress/config.js:

   export default {
     base: '/repository-name/'
   }
   
4. Deploy

   Push to main branch. Your site deploys to:

   https://username.github.io/repository/

For pnpm or yarn, uncomment the relevant sections in the workflow file and update the cache and install commands.

GitLab Pages

Deploy using GitLab CI:

1. Configure output directory

   GitLab Pages requires output in public/:

   .vitepress/config.js

   export default {
     outDir: '../public',
     base: '/repository/'  // For project pages
   }
   

   Omit base for user/group pages or custom domains.

2. Create CI configuration

   Create .gitlab-ci.yml in repository root:

   .gitlab-ci.yml

   image: node:18
   
   pages:
     cache:
       paths:
         - node_modules/
     
     script:
       - npm install
       - npm run docs:build
     
     artifacts:
       paths:
         - public
     
     only:
       - main
   
3. Deploy

   Push to the main branch to trigger the pipeline.

Azure Static Web Apps

1. Follow Azure documentation

   See the official Azure Static Web Apps guide.

2. Configure build settings

   Set these values in your configuration:

   • app_location: /
   • output_location: docs/.vitepress/dist
   • app_build_command: npm run docs:build

Firebase

1. Create Firebase config

   Create firebase.json and .firebaserc in your repository root:

   firebase.json

   {
     "hosting": {
       "public": "docs/.vitepress/dist",
       "ignore": []
     }
   }
   

   .firebaserc

   {
     "projects": {
       "default": "YOUR_FIREBASE_ID"
     }
   }
   
2. Build and deploy

   npm run docs:build
   firebase deploy
   

Surge

Quick deployment with Surge:

npm run docs:build
npx surge docs/.vitepress/dist

Custom Nginx Server

Example Nginx configuration with gzip compression and proper caching:

server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    
    listen 80;
    server_name _;
    index index.html;
    
    location / {
        # Content location
        root /app;
        
        # Exact matches -> reverse clean urls -> folders -> not found
        try_files $uri $uri.html $uri/ =404;
        
        # Non-existent pages
        error_page 404 /404.html;
        
        # Folder without index.html raises 403
        error_page 403 /404.html;
        
        # Cache headers for hashed assets
        location ~* ^/assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

Important: Do not default try_files to index.html like in SPAs. This causes invalid page state in VitePress.

This assumes your built site is in /app. Adjust the root directive for your setup.

Additional Platforms

CloudRay

Deploy with CloudRay - follow their VitePress guide

Hostinger

Deploy to Hostinger - see their deployment guide

Kinsta

Deploy to Kinsta - follow their VitePress example

Stormkit

Deploy to Stormkit - see their deployment guide

Build Options

Customize the build process with command-line options:

Output Directory

Change the build output location:

vitepress build docs --outDir ./dist

Or in config:

.vitepress/config.js

export default {
  outDir: './dist'
}

Base Path at Build Time

Override the base path during build:

vitepress build docs --base /new-base/

MPA Mode

Build as a traditional multi-page application (disables client-side routing):

vitepress build docs --mpa

Or in config:

.vitepress/config.js

export default {
  mpa: true
}

Troubleshooting

Build Fails on CI

Ensure Node.js version 18 or higher:

- uses: actions/setup-node@v6
  with:
    node-version: 24

404 on Deployment

Check your base path configuration matches your hosting setup:

• Root domain: base: '/' (default)
• Subdirectory: base: '/subdirectory/'

Assets Not Loading

Verify:

1. Base path includes trailing slash: base: '/repo/' not '/repo'
2. Assets are in docs/public/ or imported in components
3. Cache headers are properly configured

Clean URLs Not Working

Enable clean URL support on your hosting platform or disable in config:

.vitepress/config.js

export default {
  cleanUrls: false
}

Next Steps

Performance Optimization

Learn how to optimize your VitePress site for maximum performance

Custom Domain

Set up a custom domain for your deployed site

Analytics

Add analytics tracking to your VitePress site

SEO

Optimize your site for search engines