# Interface: VitePluginPixivnOptions (/pixi-vn/vite/interfaces/VitePluginPixivnOptions)



Defined in: [src/vite/plugins.ts:113](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L113)

Options for [vitePluginPixivn](/pixi-vn/vite/functions/vitePluginPixivn).

## Properties [#properties]

### assetsManifest? [#assetsmanifest]

\> `optional` **assetsManifest?**: `AssetsManifestOption`

Defined in: [src/vite/plugins.ts:293](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L293)

A PIXI.js [AssetsManifest](/pixi-vn/index/interfaces/AssetsManifest) describing all asset bundles and their aliases — or a
function that resolves one, for manifests that aren't known synchronously at
plugin-creation time (e.g. one produced by an asset pipeline such as `@assetpack/core`, or
merged together from several sources in an app-owned module).

**Prefer the function form for anything backed by a generated file.** A *static*
`import manifest from "./manifest.gen.json"` in `vite.config.ts` makes Vite treat that file
as a config dependency — restarting the whole server on every change to it — which is
disastrous when the very same config's own asset pipeline rewrites that file on every
startup: an infinite restart loop. The function form sidesteps this entirely: nothing in
`vite.config.ts` itself reads or imports the file; the plugin calls your function lazily,
from inside its own plugin hooks, whenever it needs a fresh manifest.

The function receives an `ssrLoadModule`-like loader (bound to whichever context is
available — the running dev server, or a dedicated temporary server with this plugin's own
`resolve` forwarded during `vite build`) so it can load `@/`-aliased app modules the same
way `content` / `characters` / `labels` do — e.g. to import a module that merges an asset
pipeline's generated manifest with hand-written bundles. Return `undefined` if there's
nothing to register yet (e.g. the pipeline hasn't produced output on a fresh checkout).

The plugin calls this function whenever it (re)loads content — at startup, and on every
hot-reload — and, since it generally can't know which file(s) your function's own import
depends on, also on every other file change (excluding its own generated
[VitePluginPixivnOptions.typeFilePath](#typefilepath)), so a change to a manifest generated by
another plugin is picked up without any direct coupling between the two.

Either way — plain value or function — once a manifest is registered, the plugin:

* writes `export const bundleIds` and `export const assetAliasIds` — `as const` runtime
  arrays of every bundle name and every asset alias found in the manifest — to
  [VitePluginPixivnOptions.typeFilePath](#typefilepath), and augments `PixivnBundleIds` /
  `PixivnAssetAliasIds` in `@drincs/pixi-vn/canvas` (the same `declare module` pattern used
  for `PixivnCharacterIds` / `PixivnLabelIds`), narrowing `BundleIdType` / `AssetAliasIdType`
  (also exported from `@drincs/pixi-vn/canvas`) from `string` to unions of known literals.
* seeds the dev-server's `GET /__pixi-vn/assets/manifest` endpoint with this manifest
  immediately, so it is available without the browser having to `POST` it first (see
  [PIXIVN_DEV_API_ASSETS_MANIFEST](/pixi-vn/vite/variables/PIXIVN_DEV_API_ASSETS_MANIFEST)). A later `POST` (deprecated) still overrides it.

`api.setAssetsManifest(manifest)` remains available as a lower-level escape hatch for
pushing an already-computed manifest from outside this plugin entirely (e.g. from a
separate Vite plugin that doesn't need `ssrLoadModule` access).

#### Examples [#examples]

```ts
// vite.config.ts — a manifest merged from a generated file plus hand-written bundles
vitePluginPixivn({
  typeFilePath: "./src/pixi-vn.keys.gen.ts",
  assetsManifest: async (ssrLoadModule) => {
    const mod = await ssrLoadModule("/src/assets/index.ts");
    return mod.manifest;
  },
})
```

```ts
// vite.config.ts — a genuinely static manifest, known up front
vitePluginPixivn({
  assetsManifest: { bundles: [{ name: "ui", assets: { logo: "logo.png" } }] },
  typeFilePath: "./src/pixi-vn.keys.gen.ts",
})
```

***

### autoRegisterWorker? [#autoregisterworker]

\> `optional` **autoRegisterWorker?**: `boolean`

Defined in: [src/vite/plugins.ts:228](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L228)

Auto-registers the worker generated by [VitePluginPixivnOptions.workerFilePath](#workerfilepath) by
injecting a small module into `index.html` that creates it and calls
`Game.worker.register(...)` on page load - no app code required for this part, mirroring
how [VitePluginPixivnOptions.testing](#testing) auto-injects its own bridge.

Unlike `testing`, this **is** injected during `vite build` too - the worker offloads real
runtime work (`back()`, save/export diffing), not a dev-only hook, so shipping without it
would silently lose the optimization in production.

Requires [VitePluginPixivnOptions.workerFilePath](#workerfilepath) to also be set; a project that needs
more control over the worker's lifecycle (e.g. combining it with its own message types)
should keep calling `Game.worker.register(new PixivnWorker())` by hand instead and leave
this option unset - don't do both, the second registration would just replace the first.

#### Default [#default]

```ts
false
```

#### Example [#example]

```ts
// vite.config.ts — the entire worker setup, no app code needed
vitePluginPixivn({
  workerFilePath: "./src/pixi-vn.worker.gen.ts",
  autoRegisterWorker: true,
})
```

***

### characters? [#characters]

\> `optional` **characters?**: `string` | `string`\[]

Defined in: [src/vite/plugins.ts:139](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L139)

Glob / path of module(s) whose side effects register characters via
`RegisteredCharacters.add(...)`.

Use when characters are defined separately from other content.

#### Example [#example-1]

```ts
"./src/characters.ts"
```

***

### content? [#content]

\> `optional` **content?**: `string` | `string`\[]

Defined in: [src/vite/plugins.ts:129](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L129)

Glob / path of module(s) that set up all game content as side effects:
characters, labels, hashtag-command handlers, text-replace handlers, etc.

The plugin loads these files server-side (via Vite SSR) at startup so that
every downstream plugin that depends on the registered data — most notably
`vitePluginInk` for JSON compilation — has the full registry available
before it runs.  This also works during `vite build`.

Pointing to a barrel file that re-exports everything is the simplest option.
All patterns are resolved relative to Vite `root`.

#### Examples [#examples-1]

```ts
"./src/content/index.ts"
```

```ts
"./src/content/*.ts"
```

***

### labels? [#labels]

\> `optional` **labels?**: `string` | `string`\[]

Defined in: [src/vite/plugins.ts:147](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L147)

Glob / path of module(s) whose side effects register narration labels via
`RegisteredLabels.register(...)`.

#### Example [#example-2]

```ts
"./src/*.label.ts"
```

***

### testing? [#testing]

\> `optional` **testing?**: `boolean` | \{ `windowKey?`: `string`; }

Defined in: [src/vite/plugins.ts:310](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L310)

Auto-enables `Game.testing` (see the `pixi-vn-testing` skill) for as long as the dev server
keeps running, by injecting a small module into `index.html` that calls
`Game.testing.enable(...)` on page load — no app code required for this part. **Never
injected during `vite build`**, regardless of this option.

This only turns the `window` bridge on/off. Every action it exposes still needs the app's
real `StepLabelProps` (`navigate`/`t`/`toast`/etc.) to work — the app must separately call
`Game.testing.setProps(props)` wherever it already builds those props (e.g. the end of a
`useGameProps()`-style hook), unconditionally, since `setProps` is cheap and safe to call
whether or not testing happens to be enabled.

Pass `false` to opt out entirely (e.g. a shared dev server you don't want remote-controllable).

#### Union Members [#union-members]

`boolean`

***

##### Type Literal [#type-literal]

\{ `windowKey?`: `string`; }

##### windowKey? [#windowkey]

\> `optional` **windowKey?**: `string`

The `window` property the testing API is attached under.

###### Default [#default-1]

```ts
"pixiVN"
```

#### Default [#default-2]

```ts
true
```

***

### typeFilePath? [#typefilepath]

\> `optional` **typeFilePath?**: `string`

Defined in: [src/vite/plugins.ts:171](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L171)

Path to the auto-generated TypeScript file that combines compile-time type
augmentations and runtime `as const` arrays for all currently known entity IDs.

When provided, the plugin generates (or overwrites) this file:

* after all content modules have been loaded at startup,
* after every hot-reload of a watched content file,
* whenever `api.setExternalLabels` or `api.clearExternalLabels` is called.

The generated file contains:

* `declare module` augmentations for `PixivnCharacterIds` and `PixivnLabelIds`,
  narrowing `CharacterIdType` / `LabelIdType` to unions of known string literals.
* `export const characterIds` and `export const labelIds` as `as const` arrays,
  usable at runtime for validation (e.g. `z.enum(characterIds)`).

The generated file is **excluded from HMR** so that updating it never
triggers a full-page reload.

The path may be absolute or relative to Vite `root`.

#### Example [#example-3]

```ts
"./src/pixi-vn.keys.gen.ts"
```

***

### workerFilePath? [#workerfilepath]

\> `optional` **workerFilePath?**: `string`

Defined in: [src/vite/plugins.ts:201](https://github.com/DRincs-Productions/pixi-vn/blob/5bb5bb1f92e38998ea2f477b600168d8da3ece19/src/vite/plugins.ts#L201)

Path to an auto-generated Worker entry file that hands every message it receives to
`handleGameWorkerMessage` from `@drincs/pixi-vn/worker` — the file a project needs to make
`Game.worker.register(...)` (see that function's doc comment) actually do something,
without having to hand-write and maintain that file itself.

Written once, when the plugin's config resolves (its content never changes, so unlike
[typeFilePath](#typefilepath) there's nothing to regenerate on content reload). Wire it up with
Vite's own `?worker` import:

```ts
// vite.config.ts
vitePluginPixivn({ workerFilePath: "./src/pixi-vn.worker.gen.ts" })

// wherever the app calls Game.init(...)
import { Game } from "@drincs/pixi-vn";
import PixivnWorker from "./pixi-vn.worker.gen?worker";
Game.worker.register(new PixivnWorker());
```

Purely a convenience: a project that wants a different worker setup (e.g. combining this
with its own message types on the same worker) can just write the file by hand instead and
skip this option entirely - `Game.worker.register` doesn't care which side created the file.

The path may be absolute or relative to Vite `root`.

#### Example [#example-4]

```ts
"./src/pixi-vn.worker.gen.ts"
```