Vite

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ESM syntax (like `import` and `export default`) in a Vite configuration file that is being treated as CommonJS.
  fix Ensure your `vite.config.js` file is interpreted as an ES Module. This can be done by adding `"type": "module"` to your `package.json` or by renaming `vite.config.js` to `vite.config.mjs`.

• Your current Node.js version is [X]. Vite requires Node.js version ^20.19.0 || >=22.12.0.

  cause The Node.js version running Vite does not meet the minimum requirements specified in the package's `engines` field.
  fix Upgrade your Node.js installation to version `^20.19.0` or `>=22.12.0`.

• ReferenceError: process is not defined

  cause Accessing `process.env` directly in client-side code, which is a Node.js global and not available in the browser environment.
  fix Use `import.meta.env` for environment variables in client-side code. For custom variables, ensure they are prefixed with `VITE_` (e.g., `VITE_APP_API_URL`).

• Failed to resolve import "some-package" from "src/main.ts"

  cause The imported module cannot be found in `node_modules`, its `package.json` `exports` field is misconfigured, or the import path is incorrect.
  fix Verify that `some-package` is installed correctly via `npm install some-package`. Check the module's documentation for correct import paths and ensure its `package.json` properly defines its exports for ESM environments.

• RollupError: "SymbolName" is not exported by "module-name.js"

  cause Attempting to import a named export that does not exist in the specified module, often due to incorrect CommonJS/ESM interop or misconfigured exports in a third-party library.
  fix Check the module's documentation or source code for available exports. Ensure named exports are correctly defined or consider using a default import if the module primarily uses default exports.

Warnings

• breaking Vite requires Node.js version `^20.19.0` or `>=22.12.0`.
  Fix: Upgrade your Node.js installation to version 20.19.0 or higher, or 22.12.0 or higher.
• gotcha Vite configuration files (e.g., `vite.config.js`) must be written as native ES Modules (ESM).
  Fix: Ensure your configuration file uses `export default` for its primary export and ESM `import` statements. If using a `.js` file, ensure your project's `package.json` has `"type": "module"` or rename the config file to `vite.config.mjs`.
• gotcha Environment variables exposed to client-side code must be prefixed with `VITE_`.
  Fix: Rename your environment variables (e.g., `.env` file) to `VITE_MY_VAR` and access them via `import.meta.env.VITE_MY_VAR`.
• gotcha The `esbuild` package is a peer dependency and is crucial for Vite's fast cold start and build performance. While Vite can fall back without it, it's highly recommended.
  Fix: Ensure `esbuild` is installed in your project: `npm install esbuild` or `yarn add esbuild` or `pnpm add esbuild`.
• gotcha For supporting older browsers (e.g., IE11), the `@vitejs/plugin-legacy` plugin is required.
  Fix: Install the plugin (`npm install -D @vitejs/plugin-legacy`) and add it to your `vite.config.js` plugins array.

Install

• npm install vite npm
• yarn add vite yarn
• pnpm add vite pnpm

Imports

• defineConfig

  import { defineConfig } from 'vite'

  Primarily used for configuring vite.config.ts/js files.

Quickstart

This command creates a new Vite project using the `create-vite` scaffold, setting up a React project with TypeScript. It then navigates into the project directory, installs dependencies, and starts the development server.

npm create vite@latest my-vite-app -- --template react-ts
cd my-vite-app
npm install
npm run dev