vite-plugin-fvtt 0.1.1 → 0.1.3

package/README.md

@@ -1,23 +1,23 @@
 # **vite-plugin-fvtt**
 
-A powerful [Vite](https://vitejs.dev/) plugin to **streamline and automate** the development of Foundry VTT modules and systems. It handles manifest resolution, asset copying, language file composition, and template handling with **minimal setup**, letting you focus on your code.
+A [Vite](https://vitejs.dev/) plugin to **streamline and automate** the development of Foundry VTT modules and systems.
 
-## **🚀 Key Features**
+It handles manifest resolution, asset copying, language file composition, and template handling with **minimal setup**, letting you focus on your code.
 
-The primary advantage of this plugin is the ability to develop your module in a modern, isolated environment. You no longer need to work directly inside your Foundry VTT data folder, which can be messy and inefficient. This allows you to leverage Vite's Hot Module Replacement (HMR) and other developer-friendly features without polluting your local installation.
+The plugin's core goal is to enable a robust HMR workflow via Vite's development server, freeing you from Foundry VTT's native HMR and build watch commands.
 
-## **Getting Started**
+## **🚀 Getting Started**
 
-### **1. Setup a Foundry VTT Project**
+### **Step 1. Setup a Foundry VTT Project**
 
 Create a standard [Foundry VTT module or system](https://foundryvtt.com/article/module-development/).
 Place your `module.json` or `system.json` manifest in either your **project root** or your **public/** directory.
 
-### **2. Add the Plugin to your Vite Config**
+### **Step 2. Add the Plugin to your Vite Config**
 
 Install the plugin with `npm i -D vite-plugin-fvtt`.
 
-Add the plugin to your vite.config.js. The **build.lib.entry** field is required, most of the other settings are infer'd by the plugin from your foundry manifest.
+Add the plugin to your vite.config.js. The **build.lib.entry** field is required; most of the other settings are inferred by the plugin from your Foundry VTT manifest.
 
 ```js
 // vite.config.js
@@ -37,50 +37,64 @@ export default defineConfig({
 });
 ```
 
-## **⚙️ How it Works**
+## **⚙️ Features**
 
-### **Manifest & Asset Resolution**
+### **1. Configuration**
+The plugin needs to know where your Foundry VTT instance is running to proxy and serve assets correctly. If you want to change anything from the defaults `http://localhost:30000`, create a `.env.foundryvtt.local` file in your project.
+```ini
+FOUNDRY_URL=localhost
+FOUNDRY_PORT=30000
+```
+
+The Vite dev server will run on `FOUNDRY_PORT + 1`, where you will need to open your browser manually to.
+
+### **2. Manifest & Asset Resolution**
+
+The plugin automatically detects your manifest file (`module.json` or `system.json`) in the project **root** or `public/` folder.
+
+This plugin shapes the output depending on your manifest; it tries to automatically discover the relevant files in the `root`, `source`, and `public` folders to build the output files. The `public` folder is defined by the Vite config file. The plugin determines the `source` directory based on your `lib.entry` path. For example, if your `lib.entry` is './mysource/package/main.js', the `mysource/` directory is considered your source directory.
+
+💡 Your entry file should always import your main stylesheet; the manifest dictates how everything is named and output.
+
+### **3. ESModules, Scripts & Styles**
 
-* The plugin automatically detects your manifest file (`module.json` or `system.json`) in the project **root** or `public/` folder.
-* Assets referenced in the manifest (styles, esmodules, scripts) are **automatically generated to the build output**, simplifying your build process.
+`esmodules` and `scripts` declared in your manifest are automatically created from your `lib.entry`. Since Vite compiles the module, the plugin expects the `esmodules` or `scripts` entry in your manifest to only point to a single JavaScript file.
 
-### **Template Handling**
+Stylesheets (CSS/SCSS/LESS) should be imported in your entry file; the plugin ensures they are outputted as the correct file.
 
-* The plugin automatically detects templates in common locations:
-  * Your public folder (e.g., `public/handlebars/`).
-  * The project root (e.g., `templates/`).
-  * A templates folder directly under your entry file's directory (e.g., `src/tpl/`).
-* **Note:** Only templates located in the **public folder** are copied to the build output.
+### **4. Template Handling**
 
-### **Language File Merging**
+Templates work in HMR properly on the development server; they are autodiscovered as discussed in [2. Manifest & Asset Resolution](#2-manifest--asset-resolution). The development server intercepts the websocket traffic and sends the local templates instead of Foundry VTT's, if present. e.g., a template request to `/systems/mysystem/tpl/character-header.hbs` might be rerouted to `public/tpl/character-header.hbs`. Folder structure inside your project is mirrored, apart from the `system`/`module` specific prefix.
 
-The plugin offers a powerful feature for managing translations.
+### **5. Language File Merging**
 
-* **Complete Language Files:** Place a complete JSON file (e.g., `public/lang/en.json`) and the plugin will copy it as-is.
-* **Partial Language Files:** To modularize your translations, place multiple JSON files in a subdirectory (e.g., `src/lang/en/`). The plugin will automatically **merge them into a single file** (`lang/en.json`) during the build, as specified in your manifest. The plugin looks in **root** or your **source directory** for the paths as specified in your foundry manifest file.
+Supports both complete and partial translation workflows:
 
-## **Example Project Structure**
+* **Complete files:** Place a complete JSON file (e.g., `public/lang/en.json`) and the plugin will copy it as-is.
+* **Partial files:** Place multiple JSONs inside `src/lang/en/` and the plugin merges them into one `lang/en.json` at build.
+
+Merging follows your manifest’s declared language paths, searching in root or source directories.
+
+⚠️ **Note:** HMR works for language files, but non-English locales may not reload as expected.
+
+### **Example Project Structure**
 ```
 my-module/
 ├─ src/
 │  ├─ main.js         # The primary module entry file (required by Vite).
-│  ├─ style.css       # Your project's main stylesheet.
+│  ├─ style.css       # Your project's main stylesheet, imported by main.js.
 │  └─ lang/en/        # Directory for partial, merged translation files.
 │     ├─ spells.json
 │     ├─ abilities.json
 │     └─ general.json
-├─ public/
+├─ public/            # For static assets (templates, images)
 │  ├─ module.json     # Your module's manifest file (or system.json).
 │  └─ templates/      # HTML template files for your module.
 ├─ vite.config.js     # Your Vite configuration file.
 ```
 
-## **🐛 Known Issues & Troubleshooting**
-
-* **HMR:** Hot Module Replacement may be inconsistent for non-English language files. A full page refresh or server restart might be needed.
-* **App V2:** HMR for Foundry's new App V2 has not been fully tested. If you encounter issues, please open a GitHub issue.
-* **General Issues:** If you face unexpected behavior, the first step is always to **restart your dev server (npm run dev) or run a fresh build**. This often resolves caching or HMR-related glitches.
-
 ---
 
-License: MIT
+## 📄 License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -1,7 +1,7 @@
 import fs from "fs-extra";
 import posix from "path/posix";
 import dotenv from "dotenv";
-import { sync } from "glob";
+import { globSync } from "tinyglobby";
 import { Server } from "socket.io";
 import { io } from "socket.io-client";
 
@@ -22,28 +22,6 @@ function loadEnv() {
 	};
 }
 
-//#endregion
-//#region src/config/foundryvtt-manifest.ts
-function loadManifest(config) {
-	if (context?.manifest) return context.manifest;
-	const publicDir = config.publicDir || "public";
-	const MANIFEST_LOCATIONS = [
-		"system.json",
-		"module.json",
-		`${publicDir}/system.json`,
-		`${publicDir}/module.json`
-	];
-	const foundPath = MANIFEST_LOCATIONS.map((relPath) => posix.resolve(process.cwd(), relPath)).find((absPath) => fs.pathExistsSync(absPath));
-	if (!foundPath) throw new Error(`Could not find a manifest file (system.json or module.json) in project root or ${publicDir}/.`);
-	try {
-		const data = fs.readJsonSync(foundPath);
-		data.manifestType = foundPath.includes("module.json") ? "module" : "system";
-		return data;
-	} catch (err) {
-		throw new Error(`Failed to read manifest at ${foundPath}: ${err?.message || err}`);
-	}
-}
-
 //#endregion
 //#region src/utils/logger.ts
 var Logger = class {
@@ -53,7 +31,7 @@ var Logger = class {
 		warn: "\x1B[33m",
 		error: "\x1B[31m"
 	};
-	constructor({ namespace = "vite-plugin-foundryvtt" } = {}) {
+	constructor({ namespace = "vite-plugin-fvtt" } = {}) {
 		this.namespace = namespace;
 	}
 	format(level, message) {
@@ -77,6 +55,40 @@ var Logger = class {
 };
 var logger_default = new Logger();
 
+//#endregion
+//#region src/config/foundryvtt-manifest.ts
+function loadManifest(config) {
+	if (context?.manifest) return context.manifest;
+	const publicDir = config.publicDir || "public";
+	const MANIFEST_LOCATIONS = [
+		"system.json",
+		"module.json",
+		`${publicDir}/system.json`,
+		`${publicDir}/module.json`
+	];
+	const foundPath = MANIFEST_LOCATIONS.map((relPath) => posix.resolve(process.cwd(), relPath)).find((absPath) => fs.pathExistsSync(absPath));
+	if (!foundPath) logger_default.fail(`Could not find a manifest file (system.json or module.json) in project root or ${publicDir}/.`);
+	try {
+		const data = fs.readJsonSync(foundPath);
+		if (!data.id || typeof data.id !== "string") logger_default.fail(`Manifest at ${foundPath} is missing required "id" field.`);
+		const hasEsmodules = Array.isArray(data.esmodules) && data.esmodules.length > 0;
+		const hasScripts = Array.isArray(data.scripts) && data.scripts.length > 0;
+		if (hasEsmodules === hasScripts) logger_default.fail(`Manifest at ${foundPath} must define exactly one of "esmodules" or "scripts".`);
+		const result = {
+			manifestType: foundPath.includes("module.json") ? "module" : "system",
+			id: data.id,
+			esmodules: Array.isArray(data.esmodules) ? data.esmodules : [],
+			scripts: Array.isArray(data.scripts) ? data.scripts : [],
+			styles: Array.isArray(data.styles) ? data.styles : [],
+			languages: Array.isArray(data.languages) ? data.languages : [],
+			packs: Array.isArray(data.packs) ? data.packs : []
+		};
+		return result;
+	} catch (err) {
+		logger_default.fail(`Failed to read manifest at ${foundPath}: ${err?.message || err}`);
+	}
+}
+
 //#endregion
 //#region src/config/vite-options.ts
 function createPartialViteConfig(config) {
@@ -86,7 +98,7 @@ function createPartialViteConfig(config) {
 	const fileName = (useEsModules ? context.manifest?.esmodules[0] : context.manifest?.scripts?.[0]) ?? "bundle";
 	if (fileName === "bundle") logger_default.warn("No output file specified in manifest, using default \"bundle\"");
 	if (!context.manifest?.styles?.length) logger_default.warn("No CSS file found in manifest");
-	const cssFileName = posix.parse(context.manifest?.styles[0] ?? "").name;
+	const cssFileName = posix.parse(context.manifest?.styles[0] ?? "bundle.css").name;
 	const foundryPort = context.env?.foundryPort ?? 3e4;
 	const foundryUrl = context.env?.foundryUrl ?? "localhost";
 	const entry = (config.build?.lib)?.entry;
@@ -94,16 +106,6 @@ function createPartialViteConfig(config) {
 	if (typeof entry !== "string") logger_default.fail("Only a singular string entry is supported for build.lib.entry");
 	return {
 		base,
-		esbuild: config.esbuild ?? {
-			minifyIdentifiers: false,
-			minifySyntax: true,
-			minifyWhitespace: true,
-			keepNames: true
-		},
-		server: {
-			port: foundryPort + 1,
-			proxy: { [`^(?!${base})`]: `http://${foundryUrl}:${foundryPort}` }
-		},
 		build: {
 			minify: "esbuild",
 			lib: {
@@ -113,6 +115,20 @@ function createPartialViteConfig(config) {
 				formats,
 				name: context.manifest?.id
 			}
+		},
+		define: { __FVTT_PLUGIN__: {
+			id: context.manifest?.id,
+			isSystem: context.manifest?.manifestType === "system"
+		} },
+		esbuild: config.esbuild ?? {
+			minifyIdentifiers: false,
+			minifySyntax: true,
+			minifyWhitespace: true,
+			keepNames: true
+		},
+		server: {
+			port: foundryPort + 1,
+			proxy: { [`^(?!${base})`]: `http://${foundryUrl}:${foundryPort}` }
 		}
 	};
 }
@@ -121,28 +137,80 @@ function createPartialViteConfig(config) {
 //#region src/server/hmr-client.ts
 var hmr_client_default = `
 if (import.meta.hot) {
-  function refreshApplications() {
+  const FVTT_PLUGIN = __FVTT_PLUGIN__
+
+  function refreshApplications(path = null) {
     // AppV1 refresh
     Object.values(foundry.ui.windows).forEach(app => app.render(true))
     // AppV2 refresh
-    // TODO: Can we filter out to only refresh the correct apps?
-    foundry.applications.instances.forEach(appV2 => appV2.render(true))
+    if (path)
+      foundry.applications.instances.forEach(appV2 => {
+        Object.values(appV2.constructor.PARTS ?? {}).forEach(part => {
+          const templates = Array.isArray(part.templates) ? part.templates : []
+          if (part.template === path || templates.includes(path)) appV2.render(true)
+        })
+      })
+    else foundry.applications.instances.forEach(appV2 => appV2.render(true))
   }
 
-  import.meta.hot.on('foundryvtt-template-update', async ({ path }) => {
-    console.log('Vite | Force reload template', path)
-    Handlebars.unregisterPartial(path)
-    await foundry.applications.handlebars.getTemplate(path)
-    refreshApplications()
+  import.meta.hot.on('foundryvtt-template-update', ({ path }) => {
+    game.socket.emit('template', path, response => {
+      if (response.error) new Error(response.error)
+      let template = undefined
+      try {
+        template = Handlebars.compile(response.html)
+      } catch (error) {
+        console.error(error)
+        return
+      }
+      Handlebars.registerPartial(path, template)
+      console.log(\`Vite | Retrieved and compiled template \${path}\`)
+      refreshApplications(path)
+    })
   })
 
+  async function hmrLanguage(lang, targetObject = game.i18n.translations) {
+    try {
+      const languages = FVTT_PLUGIN.isSystem
+        ? game.system.languages
+        : game.modules.get(FVTT_PLUGIN.id)?.languages
+      if (!languages) {
+        console.warn(
+          'Vite | Got a HMR request to reload languages, however no languages were found.',
+        )
+        return
+      }
+      const langEntry = languages.find(l => l.lang === lang)
+      if (!langEntry) {
+        console.warn('Vite | Got an HMR request for an undefined language')
+        return
+      }
+
+      const url = langEntry.path
+      const resp = await fetch(url)
+      if (!resp.ok) throw new Error('Failed to fetch language file!')
+
+      const json = await resp.json()
+
+      foundry.utils.mergeObject(targetObject, json)
+      console.log(\`Vite | HMR: Reloaded language '\${lang}'\`)
+    } catch (error) {
+      console.error(\`Vite | HMR: Error reloading language '\${lang}' for \${FVTT_PLUGIN.id}\`, error);
+    }
+  }
+
   import.meta.hot.on('foundryvtt-language-update', async () => {
-    console.log('Vite | Force reassigning language')
-    await game.i18n.setLanguage(game.i18n.lang)
+    const currentLang = game.i18n.lang
+    const promises = []
+    if (currentLang !== 'en') {
+      promises.push(hmrLanguage('en', game.i18n._fallback))
+    }
+    promises.push(hmrLanguage(currentLang))
+    await Promise.all(promises)
     refreshApplications()
   })
 } else console.error('Vite | HMR is disabled')
-`;
+//`;
 
 //#endregion
 //#region src/server/trackers/abstract-file-tracker.ts
@@ -330,7 +398,7 @@ function getLocalLanguageFiles(lang, outDir = false) {
 		logger_default.warn(`No language folder found at: ${sourcePath}`);
 		return [];
 	}
-	return sync(posix.join(sourcePath, "**/*.json"));
+	return globSync(posix.join(sourcePath, "**/*.json"));
 }
 function loadLanguage(lang, outDir = false) {
 	const files = getLocalLanguageFiles(lang, outDir);
@@ -486,37 +554,40 @@ function validator() {
 function foundryVTTPlugin() {
 	context.env = loadEnv();
 	return {
-		name: "vite-plugin-foundryvtt",
+		name: "vite-plugin-fvtt",
 		config(config) {
-			context.manifest = loadManifest(config);
+			context.manifest = loadManifest(config) ?? void 0;
 			return createPartialViteConfig(config);
 		},
 		configResolved(config) {
 			context.config = config;
 		},
-		async closeBundle() {
-			if (context.config?.mode !== "production") return;
-			const outDir = posix.resolve(process.cwd(), context.config.build.outDir);
+		async writeBundle() {
+			if (!context.config) return;
+			const outDir = path_utils_default.getOutDir();
 			const candidates = ["system.json", "module.json"];
 			for (const file of candidates) {
-				const src = posix.resolve(process.cwd(), file);
-				if (await fs.pathExists(src)) {
+				const src = posix.resolve(file);
+				if (!path_utils_default.getOutDirFile(file) && fs.existsSync(src)) {
+					this.addWatchFile(src);
 					const dest = posix.join(outDir, file);
 					await fs.copy(src, dest);
 					logger_default.info(`Copied ${file} >>> ${dest}`);
 				}
 			}
 			const languages = context.manifest?.languages ?? [];
-			if (languages.length > 0) {
-				for (const language of languages) {
-					if (path_utils_default.getOutDirFile(language.path) !== "") continue;
-					const languageDataRaw = loadLanguage(language.lang);
-					const languageData = transform(languageDataRaw);
-					fs.writeJSONSync(posix.join(path_utils_default.getOutDir(), language.path), languageData);
-				}
-				validator();
+			if (languages.length > 0) for (const language of languages) {
+				if (path_utils_default.getOutDirFile(language.path)) continue;
+				getLocalLanguageFiles(language.lang).forEach((langFile) => this.addWatchFile(langFile));
+				const languageDataRaw = loadLanguage(language.lang);
+				const languageData = transform(languageDataRaw);
+				fs.writeJSONSync(posix.join(outDir, language.path), languageData);
 			}
 		},
+		closeBundle() {
+			const languages = context.manifest?.languages ?? [];
+			if (languages.length > 0) validator();
+		},
 		load(id) {
 			const config = context.config;
 			const jsFileName = config.build.lib.fileName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-fvtt",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A Vite plugin for module and system development for Foundry VTT",
   "keywords": [
     "vite",
@@ -43,9 +43,9 @@
   "dependencies": {
     "dotenv": "^17.2.1",
     "fs-extra": "^11.3.1",
-    "glob": "^11.0.3",
     "socket.io": "^4.8.1",
-    "socket.io-client": "^4.8.1"
+    "socket.io-client": "^4.8.1",
+    "tinyglobby": "^0.2.14"
   },
   "peerDependencies": {
     "vite": "^7.0.0"