wallpaper-engine

Typed host contracts, Vite tooling, runtime helpers, and a development simulator for Wallpaper Engine web wallpapers.

Documentation · Demo source · Repository

wallpaper-engine lets one property schema drive Wallpaper Engine's editor metadata, inferred runtime callbacks, and a Vite development simulator. The published package has no runtime dependencies; Vite is an optional peer used only by the plugin entry point.

Install

bun add wallpaper-engine

Equivalent commands: npm install wallpaper-engine or pnpm add wallpaper-engine.

Install Vite when using wallpaper-engine/plugin:

bun add --dev vite

Quick start

// src/properties.ts
import { colorProperty } from 'wallpaper-engine/plugin';

export const properties = {
  accent: colorProperty({ text: 'Accent', value: '#60a5fa' }),
};

// vite.config.ts
import { defineConfig } from 'vite';
import { wallpaperEnginePlugin } from 'wallpaper-engine/plugin';
import { properties } from './src/properties';

export default defineConfig({
  plugins: [wallpaperEnginePlugin({ title: 'My Wallpaper', properties })],
});

// src/wallpaper.ts
import type { WallpaperUserPropertiesOf } from 'wallpaper-engine/plugin';
import { wallpaperColorToHex } from 'wallpaper-engine/helpers';
import type { properties } from './properties';
import 'wallpaper-engine';

type UserProperties = WallpaperUserPropertiesOf<typeof properties>;

window.wallpaperPropertyListener = {
  applyUserProperties(values: Partial<UserProperties>) {
    if (values.accent) {
      document.body.style.backgroundColor = wallpaperColorToHex(
        values.accent.value,
      );
    }
  },
};

Register host listeners immediately at module scope. Wallpaper Engine may send startup events before framework lifecycle hooks, and later property callbacks contain only changed keys.

By default, the Vite plugin injects the simulator during development and emits project.json during production builds. Set devtools: false to disable development injection.

Written builds preserve prior top-level Workshop metadata and preview bytes while regenerating ordinary properties, localization, and audio configuration. Configure Wallpaper Engine's browser color with schemeColor; when omitted, a valid editor-managed value from previous output is preserved.

Public entry points

Entry point	Responsibility	Format
wallpaper-engine	Project, listener, audio, media, RGB, iCUE, and ambient browser-global types	ESM + CommonJS
wallpaper-engine/plugin	Vite integration, property builders, inferred runtime types, metadata, and project links	ESM only
wallpaper-engine/helpers	Side-effect-free, tree-shakeable browser utilities	ESM + CommonJS

Full guides and exhaustive API references: shadowninex.github.io/wallpaper-engine.

Development

Run workspace commands from the repository root with Bun:

bun install
bun run dev:demo
bun run dev:docs
bun run lint
bun run typecheck
bun run test:run
bun run build

bun run build preserves the required devtools-first, library-second package build order. The documentation site has its own bun run build:docs command.

License

MIT