@studiokloek/vite-config

Shared Vite config and CLI for the Studio Kloek game projects: handlebars pages per game, Svelte, SCSS, legacy bundles, image optimisation, web manifests and, when configured, the sprites/sounds pipeline of @studiokloek/vite-assets-plugin.

Built for internal use; it expects our project layout.

Install

pnpm add -D @studiokloek/vite-config
pnpm approve-builds   # sharp, and ffmpeg-static when you use `vite.assets`

Node 22.19 or newer.

Games import packages that come in through @studiokloek/ts-core-lib and this package (pixi, capacitor, howler, vite/client, …) without declaring them. With pnpm, hoist everything like yarn did, in the game's pnpm-workspace.yaml:

shamefullyHoist: true

Usage

// package.json
"scripts": {
  "development": "kloek-development",
  "build": "kloek-build --create-zip --base=/games/2025/"
}

kloek-development [--mode <mode>] starts the dev server. kloek-build builds into public/:

| Flag | | |---|---| | -b, --base <path> | base path (default: vite.build.basePath) | | -m, --mode <mode> | Vite mode (default: production) | | -l, --log-level <level> | info, warn, error or silent | | -e, --empty-out-dir | empty public/ first (default; --no-empty-out-dir keeps it) | | -s, --sourcemaps, -i, --inline-sourcemaps | source maps (default: vite.build.sourceMaps) | | -z, --create-zip | zip the build into zips/ (default: vite.build.createZip) |

Flags you leave out take their value from package.json.

The same is available from code: kloekBuild(options), kloekDevelopment(options) and defineKloekViteConfig(env) for a vite.config.ts.

Project layout

assets/            source assets for vite.assets (tagged directories)
env/               .env files (KLOEK_* and VITE_* are exposed)
source/            Vite root
  partials/        handlebars partials; game.hbs renders every game page
  script/ style/ svelte/
  static/          public dir, copied as is
public/            build output

Every game in settings.games becomes a page <page>.html, rendered from the partial game.hbs with its settings as data. development.html lists every game.

Configuration

Everything lives in package.json. vite is validated; an unknown option is an error.

"settings": {
  "generic": { "info": { "client": "…" }, "meta": { "title": "…" }, "options": { "backgroundColor": "#000" } },
  "games": [{ "info": { "id": "verdwaald" }, "meta": { "title": "Verdwaald" } }]
},
"vite": {
  "dev": { "serveParams": "?debug", "https": true, "cors": true, "fullReloadSvelte": true },
  "build": {
    "basePath": "/",
    "legacy": false,
    "manifest": false,
    "sourceMaps": false,
    "createZip": false,
    "analyzeBundle": false,
    "cleanPatterns": []
  },
  "dedupe": []
}

Game settings are merged per section over generic. Any extra field is kept and available in the templates.

• build.imageExclude lists the directories in the build output whose images are not compressed again. By default these are the directories the assets plugin writes to (without vite.assets: sprites, sounds and fonts).
• dedupe adds packages that may only end up in the bundle once. Our own @studiokloek/* packages and everything they depend on are deduped automatically, so a linked package does not bring its own copy of pixi.js or gsap.
• Packages in the built-in vendor list (pixi, gsap, svelte, firebase, …) get their own chunk. Other packages that a page loads at the start share one vendor chunk; a package that is only imported lazily stays out of it and is not loaded at the start.
• Every build writes a licenses.txt with the licenses of the bundled packages, linked from each page.

Assets

With vite.assets in package.json, the assets plugin packs the tagged directories under assets/ before the dev server starts and before every build, and repacks on changes while developing. Paths are relative to the project. The kloek-assets CLI reads the same config, so both share their output and cache:

"vite": {
  "assets": {
    "imageQuality": { "jpeg": 80, "png": 80 },
    "output": { "directory": "source/static" },
    "scriptDirectory": "source/script",
    "sounds": { "prefixes": ["sj25"] }
  }
}

imageQuality (0–100) is the one quality setting for images: the sprite sheets are compressed with it while packing, in development too, and the loose images in the build output when building. Set sprites.compression only when the sheets need something else.

See the assets plugin for the tags and options.

Development

pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build
pnpm changeset   # describe your change; merging to main opens the release PR

License

MIT