Vite

https://v6.vite.dev
Admin
Vite is a blazing fast frontend build tool that leverages native ES modules and provides instant...
Tokens:125,338
Snippets:997
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### server.open configuration example

Source: https://v6.vite.dev/config/server-options

Sets the server to automatically open the app in the browser on server start, using the given string as the URL's pathname. The value can be a boolean or a string.

```javascript
server: {
  open: '/docs'  
}
```

--------------------------------

### configurePreviewServer hook example

Source: https://v6.vite.dev/guide/api-plugin

Use this hook to customize the preview server. Return a function from configurePreviewServer to inject a middleware after internal middlewares are installed.

```js
const myPlugin = () => ({
  name: 'configure-preview-server',
  configurePreviewServer(server) {
    // return a post hook that is called after other middlewares are
    // installed
    return () => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      })
    }
  },
})
```

--------------------------------

### createServer example usage

Source: https://v6.vite.dev/guide/api-javascript

Example of using createServer with a custom config, listening on a port, and printing URLs. Note: when using createServer and build in the same process, set process.env.NODE_ENV or mode to 'development' to avoid conflicts.

```ts
import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

const server = await createServer({
  // any valid user config options, plus `mode` and `configFile`
  configFile: false,
  root: __dirname,
  server: {
    port: 1337,
  },
})
await server.listen()

server.printUrls()
server.bindCLIShortcuts({ print: true })
```

--------------------------------

### preview function usage example

Source: https://v6.vite.dev/guide/api-javascript

Example usage of the preview function, configuring the preview server port and open option, then printing URLs and binding CLI shortcuts.

```typescript
import { preview } from 'vite'

const previewServer = await preview({
  // any valid user config options, plus `mode` and `configFile`
  preview: {
    port: 8080,
    open: true,
  },
})

previewServer.printUrls()
previewServer.bindCLIShortcuts({ print: true })
```

--------------------------------

### Generated tags for entry point views/bar.js

Source: https://v6.vite.dev/guide/backend-integration

Example of the HTML tags that should be included for the entry point `views/bar.js` in production, based on the example manifest.

```html
<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
<script type="module" src="assets/bar-gkvgaI9m.js"></script>
<!-- optional -->
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
```

--------------------------------

### Generated tags for entry point views/foo.js

Source: https://v6.vite.dev/guide/backend-integration

Example of the HTML tags that should be included for the entry point `views/foo.js` in production, based on the example manifest.

```html
<link rel="stylesheet" href="assets/foo-5UjPuW-k.css" />
<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
<script type="module" src="assets/foo-BRBmoGS9.js"></script>
<!-- optional -->
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
```

--------------------------------

### Start the Vite dev server with npm, Yarn, pnpm, Bun, or Deno

Source: https://v6.vite.dev/guide

Start the Vite dev server using the appropriate command for your package manager. The server serves index.html at http://localhost:5173.

```bash
$ npx vite
```

```bash
$ yarn vite
```

```bash
$ pnpm vite
```

```bash
$ bunx vite
```

```bash
$ deno run -A npm:vite
```

--------------------------------

### VITE_ prefix example .env file

Source: https://v6.vite.dev/guide/env-and-mode

Example .env file showing that only variables prefixed with VITE_ are exposed to client code. DB_PASSWORD is not exposed.

```env
VITE_SOME_KEY=123
DB_PASSWORD=foobar
```

--------------------------------

### Install Lightning CSS

Source: https://v6.vite.dev/guide/features

Installs the lightningcss package as a dev dependency to enable experimental Lightning CSS support in Vite.

```bash
npm add -D lightningcss
```

--------------------------------

### Install Vite from a specific commit with Bun

Source: https://v6.vite.dev/guide

Installs a specific commit of Vite using Bun. Replace SHA with any of Vite's commit SHAs.

```bash
bun add -D https://pkg.pr.new/vite@SHA
```

--------------------------------

### Start Vite dev server with createServer

Source: https://v6.vite.dev/

Use this snippet to start a Vite dev server programmatically. It imports createServer, creates a server with user config options, listens on the default port, and prints the URLs to the console. The source shows a TypeScript type annotation for the listen method, indicating it returns a Promise<ViteDevServer>.

```javascript
import { createServer } from 'vite'

const server = await createServer({
  // user config options
})
await server.listen()
server.printUrls()
```

--------------------------------

### Start Vite dev server with optional root

Source: https://v6.vite.dev/guide/cli

Starts the Vite dev server in the current directory. `vite dev` and `vite serve` are aliases for `vite`. The `[root]` argument optionally specifies the project root directory.

```bash
vite [root]
```

--------------------------------

### Install Vite CLI with npm, Yarn, pnpm, Bun, or Deno

Source: https://v6.vite.dev/guide

Install the Vite CLI as a dev dependency using your preferred package manager. Each command corresponds to npm, Yarn, pnpm, Bun, or Deno.

```bash
$ npm install -D vite
```

```bash
$ yarn add -D vite
```

```bash
$ pnpm add -D vite
```

```bash
$ bun add -D vite
```

```bash
$ deno add -D npm:vite
```

--------------------------------

### build function usage example (vite.config.js)

Source: https://v6.vite.dev/guide/api-javascript

Example usage of the build function with a root, base, and rollupOptions. Uses node:path and node:url to resolve the root path.

```typescript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { build } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

await build({
  root: path.resolve(__dirname, './project'),
  base: '/foo/',
  build: {
    rollupOptions: {
      // ...
    },
  },
})
```

--------------------------------

### Start Vite dev server with Node.js inspector (CPU profile)

Source: https://v6.vite.dev/guide/troubleshooting

Starts the Vite dev server with the built-in Node.js inspector to create a CPU profile for diagnosing slow load times. Run this command in the terminal from your project root.

```bash
vite --profile --open
```

--------------------------------

### configurePreviewServer

Source: https://v6.vite.dev/guide/api-plugin

Hook to configure the preview server. Called before other middlewares are installed; can return a post hook to inject middleware after internal middlewares.

```APIDOC
## configurePreviewServer

### Description
Hook to configure the preview server. Called before other middlewares are installed. Can return a function to inject middleware after internal middlewares are installed.

### Method
Hook (async, sequential)

### Signature
`(server: PreviewServer) => (() => void) | void | Promise<(() => void) | void>`

### Parameters
- **server** (PreviewServer) - Required - The preview server instance.

### Return Value
- A function to be called after internal middlewares are installed, or void.

### Example
```js
const myPlugin = () => ({
  name: 'configure-preview-server',
  configurePreviewServer(server) {
    // return a post hook that is called after other middlewares are
    // installed
    return () => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      })
    }
  },
})
```
```

--------------------------------

### Install CSS pre-processors

Source: https://v6.vite.dev/guide/features

Commands to install the required pre-processor packages for Sass, Less, and Stylus. Vite supports .scss, .sass, .less, .styl, and .stylus files without Vite-specific plugins.

```bash
# .scss and .sass
npm add -D sass-embedded # or sass

# .less
npm add -D less

# .styl and .stylus
npm add -D stylus
```

--------------------------------

### .env.testing with NODE_ENV=development

Source: https://v6.vite.dev/guide/env-and-mode

Example .env.testing file that sets NODE_ENV to development, allowing a development build with a custom mode.

```env
NODE_ENV=development
```

--------------------------------

### createServer

Source: https://v6.vite.dev/guide/api-javascript

Documentation for the `createServer` function from Vite's JavaScript API, including its type signature, usage example, and notes.

```APIDOC
## `createServer`

### Description
Creates a Vite dev server instance with the provided inline configuration. Returns a Promise that resolves to a `ViteDevServer` object.

### Method
`createServer` (async function)

### Endpoint
N/A - JavaScript API function

### Parameters
#### InlineConfig (object) - Optional
- `configFile` (boolean) - Optional - Set to `false` to disable config file loading.
- `root` (string) - Optional - The project root directory.
- `server` (object) - Optional - Server configuration options.
  - `port` (number) - Optional - The port to listen on.
  - `middlewareMode` (object) - Optional - Enable middleware mode. Provide the parent HTTP server for WebSocket proxy binding.
    - `server` (http.Server) - Optional - The parent HTTP server.
  - `proxy` (object) - Optional - Proxy configuration.
    - `'/ws'` (object) - Optional - Proxy rule for WebSocket connections.
      - `target` (string) - Required - The target WebSocket URL.
      - `ws` (boolean) - Optional - Set to `true` to proxy WebSocket connections.

### Request Example
```ts
import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

const server = await createServer({
  configFile: false,
  root: __dirname,
  server: {
    port: 1337,
  },
})
await server.listen()

server.printUrls()
server.bindCLIShortcuts({ print: true })
```

### Response
#### Success Response
Returns a `Promise<ViteDevServer>` that resolves to the dev server instance.

#### Response Example
```ts
const server = await createServer({ /* config */ })
// server is a ViteDevServer instance
```

### Notes
- When using `createServer` and `build` in the same Node.js process, set `process.env.NODE_ENV` or the `mode` config option to `development` to prevent conflicting behavior.
- When using middleware mode with WebSocket proxy, provide the parent HTTP server in `middlewareMode` to bind the proxy correctly.
```

--------------------------------

### Deploy with Netlify CLI

Source: https://v6.vite.dev/guide/static-deploy

Install the Netlify CLI, create a new site, and deploy to a preview URL. Use the --prod flag to deploy to production.

```bash
# Install the Netlify CLI
$ npm install -g netlify-cli

# Create a new site in Netlify
$ ntl init

# Deploy to a unique preview URL
$ ntl deploy
```

```bash
# Deploy the site into production
$ ntl deploy --prod
```

--------------------------------

### Express middleware setup for SSR dev server

Source: https://v6.vite.dev/guide/ssr

Use Vite in middleware mode with Express to have full control over the main server and decouple Vite from production. This example shows the recommended setup for an SSR dev server.

```js
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import express from 'express'
import { createServer as createViteServer } from 'vite'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const app = express()

const vite = await createViteServer({
  server: { middlewareMode: true },
  appType: 'custom'
})

app.use(vite.middlewares)
app.use('*', async (req, res) => {
  // serve index.html - we will tackle this later
})

app.listen(5173)
```

--------------------------------

### preview(inlineConfig?)

Source: https://v6.vite.dev/guide/api-javascript

Starts a preview server for the built project. Accepts an optional InlineConfig object and returns a Promise resolving to a PreviewServer instance.

```APIDOC
## `preview`

### Description
Starts a preview server for the built project. Accepts an optional InlineConfig object and returns a Promise resolving to a PreviewServer instance.

### Type Signature
```ts
async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>
```

### Parameters
- `inlineConfig` (InlineConfig) - Optional - Configuration object for the preview server, including any valid user config options, plus `mode` and `configFile`.

### Example Usage
```ts twoslash
import { preview } from 'vite'

const previewServer = await preview({
  // any valid user config options, plus `mode` and `configFile`
  preview: {
    port: 8080,
    open: true,
  },
})

previewServer.printUrls()
previewServer.bindCLIShortcuts({ print: true })
```
```

--------------------------------

### Use InferCustomEventPayload to get typed payloads

Source: https://v6.vite.dev/guide/api-plugin

After extending CustomEventMap, use InferCustomEventPayload to get the payload type for a specific event. The example shows that 'custom:foo' yields { msg: string }, while unknown events yield any. This is used with import.meta.hot.on for type-safe event handling.

```typescript
import 'vite/client'
import type { InferCustomEventPayload } from 'vite/types/customEvent.d.ts'
declare module 'vite/types/customEvent.d.ts' {
  interface CustomEventMap {
    'custom:foo': { msg: string }
  }
}
// ---cut---
type CustomFooPayload = InferCustomEventPayload<'custom:foo'>
import.meta.hot?.on('custom:foo', (payload) => {
  // The type of payload will be { msg: string }
})
import.meta.hot?.on('unknown:event', (payload) => {
  // The type of payload will be any
})
```

--------------------------------

### Preview the build locally with npm run preview

Source: https://v6.vite.dev/guide/static-deploy

Starts a local static web server serving the 'dist' folder at http://localhost:4173. Useful for checking the production build locally. Note that 'vite preview' is not meant as a production server.

```bash
$ npm run preview
```

--------------------------------

### customLogger example

Source: https://v6.vite.dev/config/shared-options

Customizes Vite's default logger to filter out empty CSS file warnings. Uses createLogger to get the default logger and overrides the warn method.

```ts
import { createLogger, defineConfig } from 'vite'

const logger = createLogger()
const loggerWarn = logger.warn

logger.warn = (msg, options) => {
  // Ignore empty CSS files warning
  if (msg.includes('vite:css') && msg.includes(' is empty')) return
  loggerWarn(msg, options)
}

export default defineConfig({
  customLogger: logger,
})
```

--------------------------------

### Scaffold a project with degit

Source: https://v6.vite.dev/guide

Scaffold a project from a GitHub template using degit, then install dependencies and start the dev server. Assumes the template repository uses 'main' as its default branch.

```bash
npx degit user/project#main my-project
cd my-project

npm install
npm run dev
```

--------------------------------

### Export bundled CSS in package.json

Source: https://v6.vite.dev/guide/build

Example package.json for a library that bundles CSS. It exports the built CSS file as './style.css' so users can import it. Requires 'type': 'module' to get the shown file extensions; without it, Vite generates .mjs and .js instead.

```json
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.umd.cjs"
    },
    "./style.css": "./dist/my-lib.css"
  }
}
```

--------------------------------

### Worker thread ModuleRunner transport and server setup

Source: https://v6.vite.dev/guide/api-environment-runtimes

Worker thread example: `worker.js` creates a ModuleRunner with a transport using `parentPort` for messaging, and `server.js` sets up a worker environment with a custom `workerHotChannel` that forwards messages. The `workerHotChannel` sets `skipFsCheck: true` because worker thread post messages are not exposed over the network.

```js
import { parentPort } from 'node:worker_threads'
import { fileURLToPath } from 'node:url'
import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'

/** @type {import('vite/module-runner').ModuleRunnerTransport} */
const transport = {
  connect({ onMessage, onDisconnection }) {
    parentPort.on('message', onMessage)
    parentPort.on('close', onDisconnection)
  },
  send(data) {
    parentPort.postMessage(data)
  },
}

const runner = new ModuleRunner(
  {
    transport,
  },
  new ESModulesEvaluator(),
)
```

```js
import { BroadcastChannel } from 'node:worker_threads'
import { createServer, RemoteEnvironmentTransport, DevEnvironment } from 'vite'

function createWorkerEnvironment(name, config, context) {
  const worker = new Worker('./worker.js')
  const handlerToWorkerListener = new WeakMap()

  const workerHotChannel = {
    // Worker threads post messages are not exposed over the network, skip server.fs checks
    skipFsCheck: true,
    send: (data) => worker.postMessage(data),
    on: (event, handler) => {
      if (event === 'connection') return

      const listener = (value) => {
        if (value.type === 'custom' && value.event === event) {
          const client = {
            send(payload) {
              worker.postMessage(payload)
            },
          }
          handler(value.data, client)
        }
      }
      handlerToWorkerListener.set(handler, listener)
      worker.on('message', listener)
    },
    off: (event, handler) => {
      if (event === 'connection') return
      const listener = handlerToWorkerListener.get(handler)
      if (listener) {
        worker.off('message', listener)
        handlerToWorkerListener.delete(handler)
      }
    },
  }

  return new DevEnvironment(name, config, {
    transport: workerHotChannel,
  })
}

await createServer({
  environments: {
    worker: {
      dev: {
        createEnvironment: createWorkerEnvironment,
      },
    },
  },
})
```

--------------------------------

### Initialize a Vite app with npm init @vitejs/app

Source: https://v6.vite.dev/blog/announcing-vite2

Run this command to scaffold a new Vite-powered project. Requires Node.js >=12.

```bash
npm init @vitejs/app
```

--------------------------------

### Install @vitejs/plugin-legacy

Source: https://v6.vite.dev/guide/using-plugins

Install the official legacy browser plugin as a dev dependency.

```bash
$ npm add -D @vitejs/plugin-legacy
```

--------------------------------

### Deploy with Vercel CLI

Source: https://v6.vite.dev/guide/static-deploy

Install the Vercel CLI, initialize a Vite project, and deploy. Vercel automatically detects Vite and applies the correct settings.

```bash
$ npm i -g vercel
$ vercel init vite
Vercel CLI
> Success! Initialized "vite" example in ~/your-folder.
- To deploy, `cd vite` and run `vercel`.
```

--------------------------------

### Install Terser for build.minify

Source: https://v6.vite.dev/config/build-options

Install Terser as a dev dependency when build.minify is set to 'terser'.

```sh
npm add -D terser
```

--------------------------------

### vite preview usage

Source: https://v6.vite.dev/guide/cli

Shows the command syntax for locally previewing the production build. Not intended as a production server.

```bash
vite preview [root]
```

--------------------------------

### Configure server.warmup with clientFiles and ssrFiles

Source: https://v6.vite.dev/config/server-options

Warm up files to transform and cache in advance, improving initial page load and preventing transform waterfalls. Accepts arrays of file paths or tinyglobby patterns relative to root. Only add frequently used files to avoid overloading the dev server on startup.

```javascript
export default defineConfig({
  server: {
    warmup: {
      clientFiles: ['./src/components/*.vue', './src/utils/big-utils.js'],
      ssrFiles: ['./src/server/modules/*.js'],
    },
  },
})
```

--------------------------------

### Reverse-order variable expansion example

Source: https://v6.vite.dev/guide/env-and-mode

Example of reverse-order variable expansion: VITE_FOO becomes foobar, VITE_BAR becomes bar.

```env
VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar
```

--------------------------------

### Configure build.lib with entry, name, formats, and fileName

Source: https://v6.vite.dev/config/build-options

Sets the library build entry point, global name, output formats, and file name pattern. Use when building a library with Vite. The entry can be a string, array, or alias map; formats supports 'es', 'cjs', 'umd', and 'iife'; fileName can be a string or a function receiving the module format.

```javascript
{
  entry: string | string[] | { [entryAlias: string]: string },
  name?: string,
  formats?: ('es' | 'cjs' | 'umd' | 'iife')[],
  fileName?: string | ((format: ModuleFormat, entryName: string) => string)
}
```

--------------------------------

### ModuleRunner example usage

Source: https://v6.vite.dev/guide/api-environment-runtimes

Example usage of ModuleRunner with a custom transport and the default ESModulesEvaluator. Imports the module runner and evaluates a module by URL.

```js
import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'
import { transport } from './rpc-implementation.js'

const moduleRunner = new ModuleRunner(
  {
    transport,
  },
  new ESModulesEvaluator(),
)

await moduleRunner.import('/src/entry-point.js')
```

--------------------------------

### Install Vite from a specific commit with pnpm

Source: https://v6.vite.dev/guide

Installs a specific commit of Vite using pnpm. Replace SHA with any of Vite's commit SHAs.

```bash
pnpm add -D https://pkg.pr.new/vite@SHA
```

--------------------------------

### Build the app with npm run build

Source: https://v6.vite.dev/guide/static-deploy

Runs the build command to compile the app. The output is placed in the 'dist' directory by default, which can be deployed to any platform.

```bash
$ npm run build
```
Tokens:
Raw