# Function: vitePluginPixivn() (/jsdoc/pixi-vn/vite/functions/vitePluginPixivn)



\> **vitePluginPixivn**(`options?`): `Plugin`

Defined in: [src/vite/plugins.ts:420](https://github.com/DRincs-Productions/pixi-vn/blob/4b8909bd13b1cc1fa7efb0238c44a5af3767e61f/src/vite/plugins.ts#L420)

Creates a Vite plugin for Pixi'VN integration.

**Static content loading**

When [VitePluginPixivnOptions.content](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#content), [VitePluginPixivnOptions.characters](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#characters), or
[VitePluginPixivnOptions.labels](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#labels) are provided, the matched files are executed server-side
via Vite SSR at startup, populating `RegisteredCharacters`, `RegisteredLabels`, and any other
singletons before downstream plugins (such as `vitePluginInk`) run — including during
`vite build`.

**Auto-generated type file**

When [VitePluginPixivnOptions.typeFilePath](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#typefilepath) is provided, the plugin writes a
TypeScript declaration file that augments `PixivnCharacterIds` in `@drincs/pixi-vn/characters`
and `PixivnLabelIds` in `@drincs/pixi-vn/narration` with all currently known IDs.
This narrows `CharacterIdType` and `LabelIdType` from `string` to unions of known literals,
giving compile-time safety for character lookups, `narration.call`, `narration.jump`, etc.

The file is regenerated whenever the character or label set changes (content reload or
external-label updates). It is **excluded from HMR** so regenerating it never triggers a page reload.

**Auto-generated worker file**

When [VitePluginPixivnOptions.workerFilePath](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#workerfilepath) is provided, the plugin writes a Worker
entry file wired to `handleGameWorkerMessage` from `@drincs/pixi-vn/worker` - see that option's
doc comment for what it's for (`Game.worker.register(...)`) and how to import it. Written once
(its content never changes), not regenerated on the triggers above. Add
[VitePluginPixivnOptions.autoRegisterWorker](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#autoregisterworker) to also skip the manual
`Game.worker.register(...)` call - the plugin creates and registers the worker itself.

**Auto-generated list file**

When VitePluginPixivnOptions.listFilePath is provided, the plugin writes a
TypeScript file that exports runtime `as const` arrays of all currently known IDs:
`characterIds` and `labelIds`. These arrays can be used for runtime validation
(e.g. `z.enum(characterIds)`) and are regenerated on the same triggers as the type file.

**Asset bundles / aliases**

When a PIXI.js `AssetsManifest` is registered — via [VitePluginPixivnOptions.assetsManifest](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#assetsmanifest)
or, for manifests produced by an async asset pipeline, `api.setAssetsManifest(manifest)` — the
same [VitePluginPixivnOptions.typeFilePath](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#typefilepath) also gets `export const bundleIds` /
`export const assetAliasIds` (`as const` arrays) plus `declare module` augmentations for
`PixivnBundleIds` / `PixivnAssetAliasIds` in `@drincs/pixi-vn/canvas` — narrowing that module's
`BundleIdType` / `AssetAliasIdType` from `string` to unions of known literals, exactly like
`PixivnCharacterIds` / `PixivnLabelIds` narrow `CharacterIdType` / `LabelIdType` above. The
manifest also immediately backs the `GET /__pixi-vn/assets/manifest` endpoint below.

**External label providers**

Other Vite plugins can inject label IDs via the plugin API without needing to register
them through SSR-loaded modules:

* `api.setExternalLabels(providerId, labels)` — registers (or replaces) the label list for
  the given provider and regenerates the type file.
* `api.clearExternalLabels(providerId)` — removes all labels for the given provider and
  regenerates the type file.

**Dev-server HTTP endpoints**

* `GET  /__pixi-vn/characters` — retrieve registered characters
* `POST /__pixi-vn/characters` — *(deprecated)* update from client; use the `characters` option instead
* `GET  /__pixi-vn/labels` — retrieve narration labels
* `POST /__pixi-vn/labels` — *(deprecated)* update from client; use the `labels` / `content` option instead
* `GET  /__pixi-vn/assets/manifest` — retrieve PIXI assets manifest (immediately available
  when the `assetsManifest` option is set or `api.setAssetsManifest` has been called; otherwise
  404 until a client `POST`)
* `POST /__pixi-vn/assets/manifest` — *(deprecated)* update from client; use the
  `assetsManifest` option instead
* `GET  /__pixi-vn/canvas-options` — retrieve canvas rendering options
* `POST /__pixi-vn/canvas-options` — update canvas options from client

**Plugin API** (consumed by `vitePluginInk`):

* `api.contentLoaded` — `Promise<void>` that resolves once all content modules have finished
  loading. Await this before generating JSON files.
* `api.characters` — the list of registered characters (populated after `contentLoaded`).
* `api.onReload(cb)` — register a callback that fires after every hot-content-reload.
* `api.setExternalLabels(providerId, labels)` — add/replace labels from an external provider.
* `api.clearExternalLabels(providerId)` — remove labels previously set for a provider.
* `api.setAssetsManifest(manifest)` — register/replace the assets manifest after
  plugin-creation time (e.g. once an async asset pipeline finishes); see
  [VitePluginPixivnOptions.assetsManifest](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions#assetsmanifest).

## Parameters [#parameters]

### options? [#options]

[`VitePluginPixivnOptions`](/jsdoc/pixi-vn/vite/interfaces/VitePluginPixivnOptions)

Optional plugin configuration.

## Returns [#returns]

`Plugin`

A Vite plugin.

## Example [#example]

```ts
// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginPixivn } from "@drincs/pixi-vn/vite";

export default defineConfig({
  plugins: [
    vitePluginPixivn({
      content: "./src/content/index.ts",
      typeFilePath: "./src/pixi-vn.gen.d.ts",
    }),
  ],
});
```