Vite as Frontend Build Tool

frontendenforced by 1 rule

Context

Modern frontend applications require a build tool to transform TypeScript and JSX into browser-compatible JavaScript, bundle modules for production, provide hot module replacement during development, and optimize assets through code splitting, minification, and tree shaking. Traditional tools like Webpack and Create React App suffer from slow development server startup, sluggish hot module replacement in large projects, complex configuration requirements, and in the case of CRA, have been deprecated.

For desktop applications with large codebases and long development sessions, build tool performance directly impacts developer productivity. Slow feedback loops during development reduce iteration speed and frustrate developers. A modern, performant build tool is essential for fast development cycles while still producing optimized production bundles.

Decision

Vite is the build tool and development server for the frontend.

Vite (version 5 or later) is the sole build tool. No other bundlers (Webpack, Parcel, Create React App) are permitted.
Configuration is defined in vite.config.ts at the frontend package root.
Use @vitejs/plugin-react for React Fast Refresh and JSX/TSX transformation.
ES Modules (ESM) are the primary module format; CommonJS (require, module.exports) is not used in frontend code.
Vite's environment variable system (.env files with VITE_ prefix) is used for configuration.
Code splitting and lazy loading via dynamic imports (React.lazy, import()) are encouraged for optimal bundle sizes.
Supports plugin-based routing solutions (e.g., TanStack Router plugin for file-based routing).

Do's and Don'ts

Do

Use Vite for all frontend projects.
Configure the build via vite.config.ts.
Use @vitejs/plugin-react for React support.
Use Vite's native ES modules support in development for instant server start.
Use Vite's built-in asset handling for images, fonts, and static resources.
Use .env files with the VITE_ prefix for environment variables.

Don't

Use Webpack, Parcel, Create React App, or other bundlers.
Use CommonJS (require, module.exports) in frontend code; use ES modules exclusively.
Eject from Vite or create overly complex custom configurations.
Commit .env.local or .env.*.local files to version control.
Manually concatenate or bundle files; let Vite handle all bundling.

Consequences

Positive

Development server starts in under one second regardless of project size, using native ES modules.
Hot module replacement reflects changes in milliseconds with React Fast Refresh.
Production builds are highly optimized through Rollup with tree shaking, code splitting, and minification.
Minimal configuration is needed out of the box with sensible defaults.
Active community and ecosystem with regular updates and comprehensive documentation.
Framework-agnostic design makes the tool future-proof.

Negative

Developers familiar with Webpack must learn Vite's configuration and plugin system.
Development mode (native ESM) and production mode (Rollup) use different bundling strategies, which can occasionally cause subtle inconsistencies.
Vite's plugin ecosystem is smaller than Webpack's, though common needs are well covered.

Enforcement rules

adrs/FE-002-vite-build-tool.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "vite-dependency-required": {
      description: "Frontend must have vite in devDependencies; no webpack/parcel configs allowed",
      async check(ctx) {
        let pkg: Record<string, unknown>;
        try {
          pkg = (await ctx.readJSON("packages/frontend/package.json")) as Record<string, unknown>;
        } catch {
          ctx.report.warning({
            message: "packages/frontend/package.json not found — cannot verify Vite dependency",
            file: "packages/frontend/package.json",
          });
          return;
        }

        const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
        const deps = (pkg.dependencies ?? {}) as Record<string, string>;
        const allDeps = { ...deps, ...devDeps };

        if (!allDeps["vite"]) {
          ctx.report.violation({
            message: "packages/frontend/package.json does not list vite as a dependency",
            file: "packages/frontend/package.json",
            fix: 'Add "vite" to devDependencies in packages/frontend/package.json',
          });
        }

        // Check for banned bundlers
        const banned = ["webpack", "parcel", "@parcel/core", "react-scripts"];

        for (const bundler of banned) {
          if (allDeps[bundler]) {
            ctx.report.violation({
              message: `packages/frontend/package.json contains banned bundler dependency "${bundler}". Use Vite instead.`,
              file: "packages/frontend/package.json",
              fix: `Remove "${bundler}" and use Vite as the build tool.`,
            });
          }
        }
      },
    },
    "vite-config-exists": {
      description: "A vite.config.ts must exist in packages/frontend/",
      async check(ctx) {
        const configs = await ctx.glob("packages/frontend/vite.config.ts");

        if (configs.length === 0) {
          ctx.report.violation({
            message:
              "packages/frontend/vite.config.ts not found. Vite requires a configuration file.",
            file: "packages/frontend/vite.config.ts",
            fix: "Create a vite.config.ts in packages/frontend/ with at least the React plugin configured.",
          });
        }

        // Also check that no webpack/parcel configs exist
        const webpackConfigs = await ctx.glob("packages/frontend/webpack.config.*");
        const parcelConfigs = await ctx.glob("packages/frontend/.parcelrc");

        for (const cfg of [...webpackConfigs, ...parcelConfigs]) {
          ctx.report.violation({
            message: `${cfg}: Non-Vite bundler configuration found. Remove it and use vite.config.ts.`,
            file: cfg,
            fix: "Delete this file and configure the build in vite.config.ts.",
          });
        }
      },
    },
  },
} satisfies RuleSet;