Function: vitePluginPixivn()

> vitePluginPixivn(options?): Plugin

Defined in: src/vite/plugins.ts:313

Creates a Vite plugin for Pixi'VN integration.

Static content loading

When VitePluginPixivnOptions.content, VitePluginPixivnOptions.characters, or 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 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 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 or, for manifests produced by an async asset pipeline, api.setAssetsManifest(manifest) — the same 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.

Parameters

options?

VitePluginPixivnOptions

Optional plugin configuration.

Returns

Plugin

A Vite plugin.

Example

// 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",
    }),
  ],
});