{"id":22968,"library":"wa-map-optimizer-vite","title":"WA Map Optimizer Vite","description":"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.","status":"active","version":"1.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/nolway/wa-map-optimizer-vite","tags":["javascript","typescript"],"install":[{"cmd":"npm install wa-map-optimizer-vite","lang":"bash","label":"npm"},{"cmd":"yarn add wa-map-optimizer-vite","lang":"bash","label":"yarn"},{"cmd":"pnpm add wa-map-optimizer-vite","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core map optimization logic; this plugin is a Vite wrapper around it.","package":"wa-map-optimizer","optional":false},{"reason":"Type validation of .tmj map files.","package":"@workadventure/tiled-map-type-guard","optional":false},{"reason":"Peer dependency; plugin used as Vite plugin.","package":"vite","optional":false}],"imports":[{"note":"ESM-only package. CommonJS require is not supported.","wrong":"const { getMaps } = require('wa-map-optimizer-vite')","symbol":"getMaps","correct":"import { getMaps } from 'wa-map-optimizer-vite'"},{"note":"Named export, not default. Must use named import syntax.","wrong":"import getMapsScripts from 'wa-map-optimizer-vite'","symbol":"getMapsScripts","correct":"import { getMapsScripts } from 'wa-map-optimizer-vite'"},{"note":"Returns an array of Vite plugin objects. Spread them into the plugins array.","wrong":"","symbol":"getMapsOptimizers","correct":"import { getMapsOptimizers } from 'wa-map-optimizer-vite'"},{"note":"This is a TypeScript type, not a runtime value. Use 'import type' to avoid runtime errors.","wrong":"import { WaMapOptimizerOptions } from 'wa-map-optimizer-vite'","symbol":"WaMapOptimizerOptions","correct":"import type { WaMapOptimizerOptions } from 'wa-map-optimizer-vite'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { getMaps, getMapsScripts, getMapsOptimizers } from 'wa-map-optimizer-vite';\n\nconst maps = getMaps('maps');\n\nexport default defineConfig({\n  build: {\n    manifest: true,\n    rollupOptions: {\n      input: {\n        ...getMapsScripts(maps)\n      }\n    }\n  },\n  plugins: [\n    ...getMapsOptimizers(maps, { logs: 1 })\n  ]\n});\n\n// Then run: npx vite build","lang":"typescript","description":"Basic setup: discovers .tmj maps from 'maps' folder, exposes scripts as Rollup entries, attaches optimizer plugins."},"warnings":[{"fix":"Ensure your map loading code expects HTML file paths for scripts (e.g., 'script.html' instead of 'script.js').","message":"In version 1.2.0, script entries now generate HTML wrapper files instead of direct JS file references.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Set build.manifest: true in your Vite config.","message":"The plugin requires Vite's build manifest to be enabled (build.manifest: true) for reliable script detection.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use Vite's 'build.outDir' to control output directory instead.","message":"The 'output' option in WaMapOptimizerOptions was deprecated and will be removed in future versions.","severity":"deprecated","affected_versions":">=1.1.28"},{"fix":"Place your map files outside 'dist' and 'node_modules', or adjust the path passed to getMaps.","message":"getMaps skips 'dist' and 'node_modules' directories automatically; if your maps are inside one of these, they will not be found.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To generate scripts, add a 'script' custom property in Tiled pointing to your JS/TS entry file.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to: import { getMaps } from 'wa-map-optimizer-vite'","cause":"Incorrect import: using default import instead of named import.","error":"TypeError: getMaps is not a function"},{"fix":"Run: npm install wa-map-optimizer","cause":"Missing peer dependency wa-map-optimizer.","error":"Error: Cannot find module 'wa-map-optimizer'"},{"fix":"Add 'build.manifest: true' to your Vite config.","cause":"build.manifest not set to true in Vite config.","error":"The 'manifest' option is not enabled. Script detection may fail."},{"fix":"Verify the path passed to getMaps exists and contains .tmj files. Path is relative to project root.","cause":"getMaps path is incorrect or directory contains no .tmj files.","error":"No maps found in the specified directory"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}