@aosengine/vite-plugin-aos

Interfaces

AosConfig

The configuration aos() contributes, as a plain object.

Properties

alias

alias: object[];

Alias entries to add, in Vite's array form.

find

find: RegExp;

replacement

replacement: string;

conditions

conditions: string[];

Resolve conditions to add.

define

define: Record<string, string>;

define entries, including import.meta.env.AOS_MODE.

exclude

exclude: string[];

Packages to keep out of the dependency pre-bundle.

guestBase

guestBase: string;

Path the guest is served from, with a leading and trailing slash.

guestOutDir

guestOutDir: string;

Where the guest lands inside the build output, relative to outDir, with a trailing slash and no leading one. This is guestBase minus the app base: an emitted file is named relative to outDir, and the base is what the server puts in front of outDir, so baking it into the file name would serve the guest from <base><base>guest/.

guestUrl

guestUrl: string;

URL of the transpiled guest entry, as the app should fetch it.

mode

mode: AosMode;

The sandbox mode the app was built for.

---

AosEnv

The environment resolveAosConfig reads.

Properties

base?

optional base?: string;

The app's public base path, as Vite resolved it. Defaults to /.

command

command: "serve" | "build";

Vite's command: serve for dev and preview, build for a production build.

env?

optional env?: Record<string, string | undefined>;

Process environment, for AOS_MODE and AOS_WASM.

viteMode?

optional viteMode?: string;

Vite's own --mode. direct and wasm select the sandbox, which is how vite build --mode direct produces a build that needs no guest component.

---

AosOptions

Options accepted by aos.

Properties

development?

optional development?: boolean;

Add the development resolve condition. Defaults to true.

exclude?

optional exclude?: readonly string[];

Extra package names kept out of the dependency pre-bundle. The wasm runtimes jolt-physics and onnxruntime-web are always excluded.

guestBase?

optional guestBase?: string;

Path the guest is served from, relative to the app base. Defaults to guest/; the transpiled entry is then guest/game.js.

guestDir?

optional guestDir?: string;

Directory holding the jco transpile output, relative to the Vite root. Defaults to build/guest, which is where scripts/build-guest.mjs writes.

mode?

optional mode?: AosMode;

Force a sandbox mode instead of deriving one.

The derivation, in order: this option, then Vite's own --mode when it is direct or wasm, then AOS_MODE in the environment, then AOS_WASM=1, then wasm for vite build and direct for vite dev.

three?

optional three?: boolean;

Alias bare three onto three/webgpu. Defaults to true.

---

AosVitePlugin

The shape of the Vite plugin object this package produces.

Typed structurally rather than as Vite's Plugin so the package carries no runtime or type dependency on a particular Vite major; a real Vite accepts it because every member matches.

Properties

enforce?

optional enforce?: "pre" | "post";

Run before Vite's own resolution, so the alias and conditions win.

name

name: string;

Plugin name, as it appears in Vite's logs.

Methods

config()?

optional config(config, env): unknown;

Contribute configuration.

Parameters

Parameter	Type	Description
config	Record<string, unknown>	The user's configuration so far.
env	{ command: "serve" | "build"; mode?: string; }	Vite's command and mode.
env.command	"serve" | "build"	-
env.mode?	string	-

Returns

unknown

A partial configuration Vite deep-merges.

configResolved()?

optional configResolved(config): void;

Record the base Vite resolved, so the guest URL is right under a sub-path.

Parameters

Parameter	Type	Description
config	{ base?: string; root?: string; }	The resolved configuration.
config.base?	string	-
config.root?	string	-

Returns

void

configureServer()?

optional configureServer(server): void;

Install the dev middlewares.

Parameters

Parameter	Type	Description
server	{ middlewares: { use: (fn) => void; }; }	The dev server.
server.middlewares	{ use: (fn) => void; }	-
server.middlewares.use	(fn) => void	-

Returns

void

generateBundle()?

optional generateBundle(this): void;

Emit the transpiled guest into the build.

Parameters

Parameter	Type	Description
this	EmitContext	The Rollup plugin context, for emitFile.

Returns

void

---

EmitContext

The slice of the Rollup plugin context the plugin uses.

Methods

emitFile()

emitFile(asset): void;

Emit one asset into the build.

Parameters

Parameter	Type	Description
asset	{ fileName: string; source: string | Uint8Array<ArrayBufferLike>; type: "asset"; }	The asset descriptor.
asset.fileName	string	-
asset.source	string | Uint8Array<ArrayBufferLike>	-
asset.type	"asset"	-

Returns

void

warn()

warn(message): void;

Report a build-time warning.

Parameters

Parameter	Type	Description
message	string	What to say.

Returns

void

Type Aliases

AosMode

type AosMode = "direct" | "wasm";

Which sandbox the app should build.

---

DevMiddleware

type DevMiddleware = (req, res, next) => void;

The slice of a connect middleware the plugin uses.

Parameters

Parameter	Type
req	{ url?: string; }
req.url?	string
res	{ statusCode: number; end: void; setHeader: void; }
res.statusCode	number
res.end
res.setHeader
next	() => void

Returns

void

Variables

ALWAYS_EXCLUDED

const ALWAYS_EXCLUDED: readonly string[];

Packages whose emscripten glue must not be pre-bundled by esbuild.

---

NEVER_INLINED

const NEVER_INLINED: readonly string[];

Extensions never inlined as a data: URI.

A wasm module inlined as base64 cannot be streamed, and an engine asset inlined into the entry chunk is downloaded before the first frame instead of alongside it.

---

PACKAGE

const PACKAGE: "@aosengine/vite-plugin-aos";

Package identity marker for @aosengine/vite-plugin-aos.

Example

import { PACKAGE } from '@aosengine/vite-plugin-aos';

console.log(PACKAGE); // '@aosengine/vite-plugin-aos'

Functions

aos()

function aos(options?): AosVitePlugin;

The aosengine Vite plugin.

Add it to plugins and the app resolves workspace packages from source, gets exactly one three, keeps the wasm runtimes out of the pre-bundle, serves .wasm correctly, and learns which sandbox to build through import.meta.env.AOS_MODE.

Parameters

Parameter	Type	Description
options	AosOptions	Mode override, guest directory and the opt-outs.

Returns

AosVitePlugin

A Vite plugin.

Example

import { aos } from '@aosengine/vite-plugin-aos';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [aos()] });

---

resolveAosConfig()

function resolveAosConfig(options, env): AosConfig;

Compute everything the plugin contributes, with no Vite involved.

Parameters

Parameter	Type	Description
options	AosOptions	The plugin options.
env	AosEnv	The Vite command, process environment and app base.

Returns

AosConfig

The configuration contribution.

Example

import { resolveAosConfig } from '@aosengine/vite-plugin-aos';

const config = resolveAosConfig({}, { command: 'serve' });
console.log(config.conditions); // ['development']
console.log(config.define['import.meta.env.AOS_MODE']); // '"direct"'

---

resolveAosMode()

function resolveAosMode(options, env): AosMode;

Decide which sandbox the app is being built for.

Parameters

Parameter	Type	Description
options	AosOptions	The plugin options.
env	AosEnv	The Vite command and process environment.

Returns

AosMode

The mode.

Example

import { resolveAosMode } from '@aosengine/vite-plugin-aos';

console.log(resolveAosMode({}, { command: 'serve' })); // 'direct'
console.log(resolveAosMode({}, { command: 'build' })); // 'wasm'