# Vite

Compile styles and deliver their CSS through Vite's module graph.

The `zyzz` plugin from `zyzz/vite` statically compiles physical source within the Vite root and serves the emitted CSS in development and builds. Vite keeps ownership of resolution, transpilation, CSS processing, and HMR. [Getting Started](/docs/introduction/getting-started) covers the setup.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Compiles source modules and delivers their CSS
  plugins: [zyzz()],
})
```

## Signature

```ts
// Creates a Vite 8 plugin
zyzz(options?)
```

## Parameters

### options.compiler

* **Type:** `boolean`
* **Default:** `true`

Rewrites authoring calls into compiled props. With `false`, the plugin still extracts and delivers CSS but keeps the authored calls, so variable sets, variants, dynamic definitions, and named stylesheet declarations need explicit identities.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Keeps authored calls in the emitted JavaScript
  plugins: [zyzz({ compiler: false })],
})
```

### options.exclude

* **Type:** `readonly (RegExp | string)[]`
* **Default:** `[]`

Source modules left out of discovery and transforms. Globs resolve against the Vite root unless they start with `**`, and regular expressions test absolute paths. Excluded modules contribute no CSS, and imports of them stay runtime imports.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Leaves a Node server entry and component stories uncompiled
  plugins: [zyzz({ exclude: ['server.mjs', /\.stories\.tsx?$/] })],
})
```

Discovery compiles every module that calls an imported function, since the function can contribute global styles. Exclude modules that run outside the application, such as a server entry that imports build output before it exists.

Modules named `vite.config.*`, `vitest.config.*`, or `vitest.workspace.*` are always excluded. Other `*.config.*` modules remain source, since application configuration such as `theme.config.ts` can define styles.

### options.include

* **Type:** `readonly string[]`
* **Default:** `[]`

Globs, files, or directories that [discovery](#discovery) scans, absolute or relative to the Vite root. A directory covers every module below it. Setting `include` replaces the `zyzz.config.*` search and nested-package skipping, and `exclude` still removes modules from the result. Nested `node_modules`, build output, and test directories stay excluded.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Scans the application's source and a linked workspace package's source
  plugins: [zyzz({ include: ['src/**', '../library/src'] })],
})
```

A pattern must start in an existing directory, and symlinks resolve to their physical paths. Directories outside the Vite root become source directories, so their modules take part in CSS delivery, initialization scripts, source maps, and hot updates.

Exclude linked authoring packages from dependency optimization, and allow directories outside the workspace through `server.fs.allow`.

### options.native

* **Type:** `Graph.compile.Options['native']`

Compiles native modules instead of web CSS. The context is captured when the plugin is created, so changing it requires a restart. Native output has no CSS delivery or initialization scripts, and requires source compilation.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Compiles native style tables for a dark iOS build
  plugins: [zyzz({ native: { colorScheme: 'dark', platform: 'ios' } })],
})
```

### options.reset

* **Type:** `boolean`
* **Default:** `false`

Adds the packaged [reset](/docs/guides/reset) to the shared CSS, in a `reset` layer ordered before authored layers. No stylesheet import is needed.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Prepends the reset layer to the delivered CSS
  plugins: [zyzz({ reset: true })],
})
```

### options.script

* **Type:** `boolean`
* **Default:** `true`

Inlines the [initialization script](/docs/api/core/defineConfig/script) of each configuration whose module uses `appearance`, `script`, or `vars` at the start of the `<head>` in `index.html`. Saved variable sets and color schemes then apply before Vite's client and application modules run.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Leaves index.html unchanged for a document that inlines script() itself
  plugins: [zyzz({ script: false })],
})
```

Applications without an `index.html`, such as server-rendered frameworks, inline `script()` in their own document.

## Returns

### plugin

* **Type:** `Plugin`

A Vite plugin with isolated compiler state for each environment. It runs before other transforms, so framework plugins receive the compiled source.

```ts title="vite.config.ts"
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Framework plugins transform the compiled modules
  plugins: [zyzz(), react()],
})
```

## Discovery

Discovery reads source modules that nothing imports yet, so their global styles reach the stylesheet from the first request. Modules the application imports compile anywhere below the Vite root or an `include` directory outside it, whatever discovery covers.

Discovery covers the first of these that applies:

1. The modules that [`include`](#optionsinclude) matches.
2. The directories that hold a `zyzz.config.*` module, found by name below the Vite root. Place the configuration at the root of the application's source, such as `src/zyzz.config.ts`, so tool configuration and scripts beside `src/` stay out.
3. The Vite root.

The `zyzz.config.*` search and a root scan skip nested packages: directories below the Vite root that hold their own `package.json`, such as a workspace's examples. [`exclude`](#optionsexclude) removes modules in every case. Adding or moving a `zyzz.config.*` module or a nested `package.json` takes full effect when the server restarts.

```txt
app/
├── examples/web/      # skipped: nested package
├── playwright.config.ts  # skipped: outside src/
├── src/
│   ├── global.ts      # discovered
│   └── zyzz.config.ts # marks src/ as the source directory
└── vite.config.ts
```

## Import Resolution

The plugin resolves the static and literal dynamic imports of each compiled module and the modules it reaches before other plugins transform them. In development, these resolves set Vite's `scan` option, as dependency scanning does, so they register no dependencies for optimization.

Plugins can check `options.scan` to tell this analysis apart from imports that reach the module graph, such as server-only imports that a framework compiler removes from client modules. Builds resolve the same imports without `scan`.

```ts title="vite.config.ts"
import { defineConfig, type Plugin } from 'vite'
import { zyzz } from 'zyzz/vite'

const serverOnly: Plugin = {
  enforce: 'pre',
  name: 'server-only',
  resolveId(source, importer, options) {
    // Zyzz scans source imports that a framework compiler may still remove
    if ('scan' in options && options.scan) return
    if (this.environment.name === 'client' && source.endsWith('.server'))
      this.error(`${importer} imports ${source}`)
  },
}

export default defineConfig({
  plugins: [zyzz(), serverOnly],
})
```

## Browser Targets

Theme colors rely on native `light-dark()`, so the plugin stops Lightning CSS from lowering it, including in application stylesheets. A client build fails only when its emitted CSS contains `light-dark()` and a CSS target would lower it or names no browser.

When `build.cssTarget` is unset and `build.target` names no browser, such as `node20` or `es2022`, CSS targets default to Chrome and Edge 123, Firefox 120, and Safari 17.5. A browser `build.target` stays the CSS target, as in Vite.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Lowers modern CSS for Chrome 120, which passes while no stylesheet uses light-dark()
  build: { cssTarget: 'chrome120', target: 'es2022' },
  plugins: [zyzz()],
})
```

### Server Builds

Server environments, including `build.ssr` builds, collect CSS for rendering without shipping it, so they skip the CSS target check. A Node `build.target` needs no separate CSS target.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Builds the server entry with theme colors and no browser CSS target
  build: {
    rolldownOptions: { input: 'src/server.ts' },
    ssr: true,
    target: 'node20',
  },
  plugins: [zyzz()],
})
```

## Dependency Optimization

Compiled modules import `zyzz/runtime`, which Vite's dependency scan cannot find in authored source. The development server adds it to `optimizeDeps.include` in each environment that discovers dependencies, so serving the first compiled module does not re-run the optimizer.

Environments that set `optimizeDeps.noDiscovery`, as Vite's default SSR environment does, keep their explicit lists. So do configurations that exclude `zyzz` or `zyzz/runtime`, and linked or aliased copies outside `node_modules`, which Vite serves as source. Output from `compiler: false` imports no runtime.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  environments: {
    // Pre-bundles zyzz/runtime with the server's discovered dependencies
    ssr: {
      optimizeDeps: { noDiscovery: false },
      resolve: { noExternal: true },
    },
  },
  plugins: [zyzz()],
})
```

## Errors

A client build fails when emitted CSS uses `light-dark()` and a CSS target cannot preserve it or cannot be verified. Configuration fails when an `include` pattern does not start in an existing directory, and when `native` is combined with `reset` or `compiler: false`. Source errors keep their locations.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'

export default defineConfig({
  // Rejected once a stylesheet uses light-dark(), which Safari 15 would lower
  build: { cssTarget: 'safari15' },
  plugins: [zyzz()],
})
```

A failed development rebuild keeps the previous complete output until the source is fixed. Circular static imports between authored modules fail compilation, and virtual modules and authoring inside framework single-file components are not compiled.
