WA Map Optimizer Vite

1.2.4 verified Mon Apr 27 auth: no javascript

Vite plugin for optimizing WorkAdventure Tiled (.tmj) maps. Version 1.2.4, released March 2026. Integrates wa-map-optimizer into Vite build pipeline: recursively discovers .tmj maps, validates structure, runs optimizer, rewrites 'script' and 'mapImage' custom properties to point to hashed Vite output. Generates HTML wrapper files for scripts. Supports configurable Play URL via options or PLAY_URL env var. Active maintenance with monthly releases.

Common errors

error TypeError: getMaps is not a function ↓

cause Incorrect import: using default import instead of named import.

fix

Change to: import { getMaps } from 'wa-map-optimizer-vite'

error Error: Cannot find module 'wa-map-optimizer' ↓

cause Missing peer dependency wa-map-optimizer.

fix

Run: npm install wa-map-optimizer

error The 'manifest' option is not enabled. Script detection may fail. ↓

cause build.manifest not set to true in Vite config.

fix

Add 'build.manifest: true' to your Vite config.

error No maps found in the specified directory ↓

cause getMaps path is incorrect or directory contains no .tmj files.

fix

Verify the path passed to getMaps exists and contains .tmj files. Path is relative to project root.

Warnings

breaking In version 1.2.0, script entries now generate HTML wrapper files instead of direct JS file references. ↓

fix Ensure your map loading code expects HTML file paths for scripts (e.g., 'script.html' instead of 'script.js').

gotcha The plugin requires Vite's build manifest to be enabled (build.manifest: true) for reliable script detection. ↓

fix Set build.manifest: true in your Vite config.

deprecated The 'output' option in WaMapOptimizerOptions was deprecated and will be removed in future versions. ↓

fix Use Vite's 'build.outDir' to control output directory instead.

gotcha getMaps skips 'dist' and 'node_modules' directories automatically; if your maps are inside one of these, they will not be found. ↓

fix Place your map files outside 'dist' and 'node_modules', or adjust the path passed to getMaps.

gotcha If no script property is defined on a map, the map is still optimized but no HTML wrapper is generated. The mapImage property is optional. ↓

fix To generate scripts, add a 'script' custom property in Tiled pointing to your JS/TS entry file.

Install

npm install wa-map-optimizer-vite

yarn add wa-map-optimizer-vite

pnpm add wa-map-optimizer-vite

Imports

getMaps

wrong

const { getMaps } = require('wa-map-optimizer-vite')

correct

import { getMaps } from 'wa-map-optimizer-vite'

ESM-only package. CommonJS require is not supported.

getMapsScripts

wrong

import getMapsScripts from 'wa-map-optimizer-vite'

correct

import { getMapsScripts } from 'wa-map-optimizer-vite'

Named export, not default. Must use named import syntax.

getMapsOptimizers
```
import { getMapsOptimizers } from 'wa-map-optimizer-vite'
```
Returns an array of Vite plugin objects. Spread them into the plugins array.

WaMapOptimizerOptions

wrong

import { WaMapOptimizerOptions } from 'wa-map-optimizer-vite'

correct

import type { WaMapOptimizerOptions } from 'wa-map-optimizer-vite'

This is a TypeScript type, not a runtime value. Use 'import type' to avoid runtime errors.

Quickstart

Basic setup: discovers .tmj maps from 'maps' folder, exposes scripts as Rollup entries, attaches optimizer plugins.

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

const maps = getMaps('maps');

export default defineConfig({
  build: {
    manifest: true,
    rollupOptions: {
      input: {
        ...getMapsScripts(maps)
      }
    }
  },
  plugins: [
    ...getMapsOptimizers(maps, { logs: 1 })
  ]
});

// Then run: npx vite build