Vite Configuration

Astro is built on top of Vite, a fast and modern build tool. You can pass additional Vite configuration options through the vite key in your Astro config.

Basic Vite Configuration

Add Vite configuration to your astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    // Vite configuration options here
  }
});

Astro automatically configures Vite with sensible defaults. Only add custom Vite config when you need to override or extend the defaults.

Common Use Cases

Adding Vite Plugins

Extend Vite with community plugins:

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()]
  }
});

Many popular tools have Astro integrations that handle Vite configuration for you. Check the integrations directory first.

Configuring SSR External Packages

Exclude problematic packages from SSR processing:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    ssr: {
      external: ['broken-npm-package']
    }
  }
});

When to use ssr.external

Use this when a package:

Has CommonJS modules that break during SSR
Uses Node.js built-ins that need to be excluded
Has incompatible dependencies
Causes “Cannot use import statement outside a module” errors

Adding Module Aliases

Create import aliases (TypeScript users should also update tsconfig.json):

astro.config.mjs

import { defineConfig } from 'astro/config';
import path from 'path';

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        '@components': path.resolve('./src/components'),
        '@lib': path.resolve('./src/lib')
      }
    }
  }
});

Then use in your code:

src/pages/index.astro

---
import Card from '@components/Card.astro';
import { formatDate } from '@lib/utils';
---

Astro provides @/* as an alias to src/* by default. For TypeScript projects, also configure path mappings in tsconfig.json.

Environment Variables

Customize which environment variables are exposed to your client-side code:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    define: {
      'import.meta.env.CUSTOM_VAR': JSON.stringify(process.env.CUSTOM_VAR)
    }
  }
});

Only use define for non-secret values. Secrets should never be exposed to client code.

Optimizing Dependencies

Control which dependencies Vite pre-bundles:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    optimizeDeps: {
      include: ['linked-package'],
      exclude: ['heavy-package']
    }
  }
});

When to optimize dependencies

Include when:

A package is linked locally and not being detected
A package has many internal modules that slow down dev server
You’re experiencing slow initial page loads

Exclude when:

A package is very large and slows down the dev server startup
A package has conditional imports that break when pre-bundled

Advanced Configuration

Build Options

Customize the build output:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            'vendor': ['react', 'react-dom']
          }
        }
      },
      cssMinify: 'lightningcss',
      minify: 'terser'
    }
  }
});

Vite uses Rollup for production builds. Use rollupOptions to configure Rollup directly.

CSS Configuration

Configure CSS processing:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "src/styles/variables.scss";`
        }
      }
    }
  }
});

Server Options

Configure the Vite dev server:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    server: {
      fs: {
        allow: ['..']  // Allow serving files from parent directory
      },
      watch: {
        usePolling: true  // Use polling for file watching (useful in Docker)
      }
    }
  }
});

Common server options

server.fs.allow: Restrict file system access for security
server.watch.usePolling: Enable polling for file watching (Docker, WSL)
server.proxy: Configure proxy for API requests
server.cors: Enable CORS for development

Proxy Configuration

Proxy API requests during development:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    server: {
      proxy: {
        '/api': {
          target: 'http://localhost:3000',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    }
  }
});

Now requests to /api/users are proxied to http://localhost:3000/users.

Framework-Specific Configuration

React

Customize React plugin options:

astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [react()],
  vite: {
    esbuild: {
      jsxInject: `import React from 'react'`
    }
  }
});

Vue

Configure Vue plugin:

astro.config.mjs

import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

export default defineConfig({
  integrations: [vue()],
  vite: {
    vue: {
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('ion-')
        }
      }
    }
  }
});

Performance Optimization

Code Splitting

Optimize bundle size with manual chunks:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks(id) {
            if (id.includes('node_modules')) {
              if (id.includes('react')) {
                return 'vendor-react';
              }
              return 'vendor';
            }
          }
        }
      }
    }
  }
});

Benefits

Smaller initial bundle
Better caching
Parallel downloads

Trade-offs

More HTTP requests
Complex configuration
Overhead for small sites

Asset Optimization

Configure asset handling:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    build: {
      assetsInlineLimit: 4096,  // 4kb
      cssCodeSplit: true
    }
  }
});

assetsInlineLimit: Assets smaller than this are inlined as base64
cssCodeSplit: Enable CSS code splitting

Environment-Specific Configuration

Configure Vite differently for dev vs. build:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig(({ command, mode }) => {
  const isDev = command === 'dev';
  
  return {
    vite: {
      logLevel: isDev ? 'info' : 'warn',
      build: {
        sourcemap: isDev,
        minify: !isDev
      }
    }
  };
});

The config function receives command (“dev” | “build” | “preview”) and mode (“development” | “production”).

Debugging Vite

Enable Debug Logging

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    logLevel: 'info',  // 'error' | 'warn' | 'info' | 'silent'
    clearScreen: false
  }
});

Inspect Bundle

Use the rollup-plugin-visualizer to analyze your bundle:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  vite: {
    plugins: [
      visualizer({
        open: true,
        gzipSize: true,
        brotliSize: true
      })
    ]
  }
});

Run astro build to generate a visual report of your bundle.

Common Issues

Module not found errors

Try adding the module to vite.optimizeDeps.include:

astro.config.mjs

export default defineConfig({
  vite: {
    optimizeDeps: {
      include: ['problematic-package']
    }
  }
});

Slow dev server startup

Exclude large dependencies from optimization:

astro.config.mjs

export default defineConfig({
  vite: {
    optimizeDeps: {
      exclude: ['large-package']
    }
  }
});

SSR errors with CommonJS packages

Mark the package as external:

astro.config.mjs

export default defineConfig({
  vite: {
    ssr: {
      external: ['cjs-package']
    }
  }
});

File watching not working (Docker/WSL)

Enable polling:

astro.config.mjs

export default defineConfig({
  vite: {
    server: {
      watch: {
        usePolling: true
      }
    }
  }
});

Complete Example

Here’s a comprehensive Vite configuration example:

astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import path from 'path';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  integrations: [react()],
  vite: {
    // Plugins
    plugins: [tailwindcss()],
    
    // Aliases
    resolve: {
      alias: {
        '@components': path.resolve('./src/components'),
        '@lib': path.resolve('./src/lib')
      }
    },
    
    // SSR Configuration
    ssr: {
      external: ['@prisma/client']
    },
    
    // Dependency Optimization
    optimizeDeps: {
      include: ['linked-package'],
      exclude: ['heavy-package']
    },
    
    // Build Options
    build: {
      sourcemap: true,
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['react', 'react-dom']
          }
        }
      }
    },
    
    // CSS Options
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "src/styles/variables.scss";`
        }
      }
    },
    
    // Server Options
    server: {
      proxy: {
        '/api': 'http://localhost:3000'
      },
      watch: {
        usePolling: process.env.USE_POLLING === 'true'
      }
    }
  }
});

Learn More

Vite Documentation

Official Vite configuration reference

Astro Config

Complete Astro configuration reference

Integrations

Learn about Astro integrations

Build Options

Astro build configuration

Get Started

Core Concepts

Features

Integrations

Configuration

Guides

Vite Configuration

Basic Vite Configuration

Common Use Cases

Adding Vite Plugins

Configuring SSR External Packages

Adding Module Aliases

Environment Variables

Optimizing Dependencies

Advanced Configuration

Build Options

CSS Configuration

Server Options

Proxy Configuration

Framework-Specific Configuration

React

Vue

Performance Optimization

Code Splitting

Benefits

Trade-offs

Asset Optimization

Environment-Specific Configuration

Debugging Vite

Enable Debug Logging

Inspect Bundle

Common Issues

Complete Example

Learn More

Vite Documentation

Astro Config

Integrations

Build Options

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Integrations

Configuration

Guides

​Basic Vite Configuration

​Common Use Cases

​Adding Vite Plugins

​Configuring SSR External Packages

​Adding Module Aliases

​Environment Variables

​Optimizing Dependencies

​Advanced Configuration

​Build Options

​CSS Configuration

​Server Options

​Proxy Configuration

​Framework-Specific Configuration

​React

​Vue

​Performance Optimization

​Code Splitting

Benefits

Trade-offs

​Asset Optimization

​Environment-Specific Configuration

​Debugging Vite

​Enable Debug Logging

​Inspect Bundle

​Common Issues

​Complete Example

​Learn More

Vite Documentation

Astro Config

Integrations

Build Options

Build docs developers (and LLMs) love

Basic Vite Configuration

Common Use Cases

Adding Vite Plugins

Configuring SSR External Packages

Adding Module Aliases

Environment Variables

Optimizing Dependencies

Advanced Configuration

Build Options

CSS Configuration

Server Options

Proxy Configuration

Framework-Specific Configuration

React

Vue

Performance Optimization

Code Splitting

Asset Optimization

Environment-Specific Configuration

Debugging Vite

Enable Debug Logging

Inspect Bundle

Common Issues

Complete Example

Learn More