WA Map Optimizer Vite Plugin

Vite plugin to optimize WorkAdventure Tiled (.tmj) maps using wa-map-optimizer, and to wire Tiled "script" and "mapImage" properties to your built assets automatically.

• Recursively discovers .tmj maps
• Validates map structure (using @workadventure/tiled-map-type-guard)
• Runs wa-map-optimizer during Vite build
• Rewrites the "script" map property to the hashed JS asset built by Vite
• Copies the file referenced by "mapImage" alongside the optimized map and updates the property

Installation

npm i -D wa-map-optimizer-vite

Quick start

1. In Tiled, add optional custom properties on your map:

• script (string): relative path to a JS/TS entry you want built by Vite
• mapImage (string): relative path to an image you want copied next to the optimized map

Example (excerpt of your .tmj):

{
  "properties": [
    { "name": "script", "type": "string", "value": "./scripts/myScene.ts" },
    { "name": "mapImage", "type": "string", "value": "./images/preview.png" }
  ]
}

2. Configure Vite to discover maps, declare script entries, and attach the optimizer plugins:

// vite.config.ts
import { defineConfig } from 'vite';
import { getMaps, getMapsScripts, getMapsOptimizers, type WaMapOptimizerOptions } from 'wa-map-optimizer-vite';

// Discover maps (pass the folder containing your .tmj files)
const maps = getMaps('maps');

// Optional: customize optimizer options (passed to wa-map-optimizer)
const optimizeOptions: WaMapOptimizerOptions = {
  logs: 1, // 0=silent ... 3=verbose (see wa-map-optimizer LogLevel)
  // output: { path: 'dist' } // defaults to 'dist'
  // playUrl: 'https://play.workadventu.re' // defaults to process.env.PLAY_URL or 'https://play.workadventu.re'
};

export default defineConfig({
  build: {
    // Recommended: generate a build manifest so the plugin can
    // robustly discover the compiled entry files
    manifest: true,
    rollupOptions: {
      // Expose each Tiled "script" as a named entry so Vite builds hashed assets
      input: {
        ...getMapsScripts(maps)
      }
    },
    // outDir should match your base output (defaults to 'dist')
    // outDir: 'dist'
  },
  plugins: [
    // One optimizer plugin instance per map
    ...getMapsOptimizers(maps, optimizeOptions)
  ]
});

3. Build your project:

vite build

After the build:

• Each map is optimized into dist/<original_map_dir>/.tmj
• If a map has a "mapImage" property, the image is copied next to the optimized map and the property is updated
• If a map has a "script" property:
  • The script is compiled into a hashed JS file (e.g., myscript-12345678.js)
  • An HTML wrapper file is generated with the same hash (e.g., myscript-12345678.html) that loads both the WorkAdventure iframe API and the compiled script
  • The "script" property is replaced by the path to the HTML file

Configuration options

playUrl

You can configure the WorkAdventure Play URL used in the generated HTML wrapper files in three ways (in order of priority):

1. Pass it in the WaMapOptimizerOptions:

const optimizeOptions: WaMapOptimizerOptions = {
  playUrl: 'https://play.workadventu.re'
};

2. Set the PLAY_URL environment variable:

export PLAY_URL=https://play.workadventu.re
vite build

3. If neither is set, it defaults to https://play.workadventu.re

How it works

• getMaps walks the provided directory (skipping dist and node_modules), validates .tmj files, and returns a Map of path -> ITiledMap
• getMapsScripts returns a Rollup/Vite input object mapping each map script name to its source path
• getMapsOptimizers returns an array of Vite plugins; during writeBundle each plugin:
  • runs wa-map-optimizer to generate the optimized .tmj and tileset chunks
  • optionally copies the mapImage file next to the optimized map and updates the property
  • reads the Vite build manifest (dist/manifest.json) to locate the compiled entry for the declared script (falls back to scanning dist/assets)
  • generates an HTML wrapper file that includes the WorkAdventure iframe API and the compiled script
  • rewrites the map "script" property to point to the HTML wrapper file

Notes:

• The base output folder defaults to dist. You can override via OptimizeOptions.output.path (or WaMapOptimizerOptions.output.path)
• Tileset names are automatically prefixed with -chunk and suffixed with a short shake256 digest
• The HTML wrapper uses the playUrl option (or PLAY_URL env variable, or defaults to https://play.workadventu.re) for the iframe_api.js script
• Compatibility: Vite 4+. For best results, enable build.manifest: true.