Interface: VitePluginPixivnOptions

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

Options for vitePluginPixivn.

Properties

assetsManifest?

> optional assetsManifest?: AssetsManifestOption

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

A PIXI.js 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), 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, 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). 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

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

// 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?

> optional autoRegisterWorker?: boolean

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

Auto-registers the worker generated by VitePluginPixivnOptions.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 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 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

false

Example

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

characters?

> optional characters?: string | string[]

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

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

Use when characters are defined separately from other content.

Example

"./src/characters.ts"

content?

> optional content?: string | string[]

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

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

"./src/content/index.ts"

"./src/content/*.ts"

labels?

> optional labels?: string | string[]

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

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

Example

"./src/*.label.ts"

testing?

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

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

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

boolean

Type Literal

{ windowKey?: string; }

windowKey?

> optional windowKey?: string

The window property the testing API is attached under.

Default

"pixiVN"

Default

true

typeFilePath?

> optional typeFilePath?: string

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

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

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

workerFilePath?

> optional workerFilePath?: string

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

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 there's nothing to regenerate on content reload). Wire it up with Vite's own ?worker import:

// 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

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