@jmlweb/vite-config

Base Vite configuration for jmlweb projects. Provides sensible defaults for TypeScript support, build optimization, and development server settings.

✨ Features

• 🎯 Sensible Defaults: Pre-configured with optimized build and dev server settings
• 📦 TypeScript Support: Works seamlessly with TypeScript projects
• ⚛️ React Ready: Optional React integration via plugin injection
• 📁 Path Aliases: Easy configuration for module path resolution
• 🔧 Clean API: Simple functions to create configurations
• 🛠️ Fully Typed: Complete TypeScript support with exported types

📦 Installation

pnpm add -D @jmlweb/vite-config vite

For React projects, also install the React plugin:

pnpm add -D @vitejs/plugin-react

💡 Upgrading from a previous version? See the Migration Guide for breaking changes and upgrade instructions.

🚀 Quick Start

Create a vite.config.ts file in your project root:

import { createViteConfig } from '@jmlweb/vite-config';

export default createViteConfig();

💡 Examples

Basic Setup

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';

export default createViteConfig();

With Path Aliases

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import { resolve } from 'path';

export default createViteConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
      '@components': resolve(__dirname, './src/components'),
      '@utils': resolve(__dirname, './src/utils'),
    },
  },
});

With React Plugin

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';

export default createViteConfig({
  plugins: [react()],
});

Using the React-Specific Helper

// vite.config.ts
import { createReactViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';

export default createReactViteConfig({
  reactPlugin: react(),
  resolve: {
    alias: {
      '@': './src',
    },
  },
});

With Custom Build Settings

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';

export default createViteConfig({
  build: {
    sourcemap: true,
    target: ['es2020', 'chrome87', 'firefox78', 'safari14'],
    outDir: 'build',
  },
});

With Custom Server Settings

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';

export default createViteConfig({
  server: {
    port: 3000,
    open: true,
    host: true, // Listen on all addresses
  },
});

With Multiple Plugins

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';

export default createViteConfig({
  plugins: [react(), svgr()],
  resolve: {
    alias: {
      '@': './src',
    },
  },
});

Full Configuration Example

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';

export default createViteConfig({
  plugins: [
    react({
      babel: {
        plugins: ['@emotion/babel-plugin'],
      },
    }),
  ],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
  build: {
    sourcemap: true,
    target: 'es2020',
  },
  server: {
    port: 3000,
    open: true,
  },
  preview: {
    port: 4000,
  },
});

🤔 Why Use This?

Philosophy: Modern build tools should provide instant feedback during development and optimized production builds with zero configuration.

This package provides a Vite configuration that balances development speed with production optimization. It leverages Vite's native ESM dev server for instant HMR and esbuild for ultra-fast production builds, while remaining flexible enough for any project type.

Design Decisions

ESBuild Minification (minify: 'esbuild'): Fast production builds

• Why: esbuild is orders of magnitude faster than terser while producing comparably small bundles. For most projects, the speed improvement far outweighs the minimal size difference. This keeps build times fast even for large applications
• Trade-off: Terser can sometimes achieve slightly smaller bundles (1-3%). But esbuild's speed is almost always worth it
• When to override: For bundle size-critical applications where every byte matters, consider terser. But try esbuild first

ESNext Target (target: 'esnext'): Modern JavaScript output

• Why: Vite assumes modern browsers by default. Using esnext target produces the smallest, most performant code because it doesn't transpile modern features browsers already support. Your bundler only polyfills what's actually needed
• Trade-off: Won't work in older browsers without additional configuration. But Vite is designed for modern development
• When to override: For projects supporting older browsers - set specific targets like ['es2020', 'chrome87', 'firefox78']

No Source Maps by Default (sourcemap: false): Faster production builds

• Why: Source maps are valuable for debugging but significantly increase build time and bundle size. Most production deployments don't need them. Enable per-project when needed for production debugging or error tracking services
• Trade-off: Harder to debug production issues. But you can enable source maps easily when needed
• When to override: For production debugging or when using error tracking services (Sentry, etc.) - set sourcemap: true

Port Flexibility (strictPort: false): Development convenience

• Why: If the default port is in use, Vite automatically finds an available port instead of failing. This is convenient when running multiple projects or when the port is already taken
• Trade-off: Port might change between runs if default is busy. But Vite tells you the actual port
• When to override: For projects that must run on a specific port (e.g., configured in OAuth callbacks) - set strictPort: true

📋 Configuration Details

Default Settings

| Category | Setting | Default Value | Description | | -------- | ------------ | ------------- | ------------------------------- | | Build | outDir | 'dist' | Output directory for production | | Build | sourcemap | false | Source map generation | | Build | minify | 'esbuild' | Minification strategy | | Build | target | 'esnext' | Build target environment | | Server | port | 5173 | Development server port | | Server | strictPort | false | Fail if port is in use | | Server | open | false | Open browser on start | | Server | host | 'localhost' | Host to bind to | | Preview | port | 4173 | Preview server port |

API Reference

createViteConfig(options?: ViteConfigOptions): UserConfig

Creates a Vite configuration with sensible defaults.

Parameters:

| Option | Type | Description | | --------- | ------------------------- | -------------------------------- | | plugins | Plugin[] | Vite plugins to include | | resolve | { alias?: Record<...> } | Module resolution configuration | | build | BuildOptions | Build configuration options | | server | ServerOptions | Development server configuration | | preview | PreviewOptions | Preview server configuration | | options | Partial<UserConfig> | Additional Vite options to merge |

Returns: A complete Vite UserConfig object.

createReactViteConfig(options: ViteConfigOptions & { reactPlugin: Plugin }): UserConfig

Creates a Vite configuration optimized for React applications.

Parameters:

| Option | Type | Description | | ------------- | ------------------- | ------------------------------------ | | reactPlugin | Plugin | The React plugin instance (required) | | ... | ViteConfigOptions | All options from createViteConfig |

Returns: A complete Vite UserConfig object with React plugin included.

Exported Constants

• BASE_DEFAULTS - Default configuration values for reference
• UserConfig, Plugin - Re-exported from Vite

🎯 When to Use

Use this configuration when you want:

• ✅ Consistent Vite configuration across multiple projects
• ✅ Optimized build settings out of the box
• ✅ Easy integration with React and other plugins
• ✅ Type-safe configuration with full TypeScript support
• ✅ A clean, simple API for customization

🔧 Extending the Configuration

You can extend the configuration for your specific needs:

Adding Custom Plugins

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';
import { visualizer } from 'rollup-plugin-visualizer';

export default createViteConfig({
  plugins: [react(), svgr(), visualizer({ open: true })],
});

Overriding Build Settings

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';

export default createViteConfig({
  build: {
    sourcemap: true,
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
});

Environment-Specific Configuration

// vite.config.ts
import { createViteConfig } from '@jmlweb/vite-config';
import react from '@vitejs/plugin-react';

export default createViteConfig({
  plugins: [react()],
  build: {
    sourcemap: process.env.NODE_ENV !== 'production',
  },
  server: {
    proxy: {
      '/api': 'http://localhost:3001',
    },
  },
});

📝 Usage with Scripts

Add build scripts to your package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "typecheck": "tsc --noEmit"
  }
}

Then run:

pnpm dev      # Start development server
pnpm build    # Build for production
pnpm preview  # Preview production build

📋 Requirements

• Node.js >= 18.0.0
• Vite >= 5.0.0

📦 Peer Dependencies

This package requires the following peer dependency:

• vite (>=5.0.0)

Optional peer dependency for React projects:

• @vitejs/plugin-react (for React integration)

🔗 Related Packages

Internal Packages

• @jmlweb/tsconfig-react - TypeScript config for React projects
• @jmlweb/eslint-config-react - ESLint config for React projects
• @jmlweb/vitest-config - Vitest configuration for testing
• @jmlweb/prettier-config-base - Prettier config for consistent formatting

External Tools

• Vite - Next-generation frontend tooling
• @vitejs/plugin-react - Official React plugin for Vite
• vite-plugin-svgr - SVG to React component transform
• rollup-plugin-visualizer - Visualize bundle size

🔄 Migration Guide

Upgrading to a New Version

Note: If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.

No breaking changes have been introduced yet. This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.

For version history, see the Changelog.

Need Help? If you encounter issues during migration, please open an issue.

📜 Changelog

See CHANGELOG.md for version history and release notes.

📄 License

MIT