foundry-vtt-react 0.1.4 → 0.1.5

package/README.md

@@ -1,14 +1,12 @@
 # Foundry VTT React
 
-This package provides extensions of various Foundry VTT classes to support building React applications inside Foundry VTT.
-
-It is a **library**, consumed by module developers — not a Foundry module itself.
-
-This is a bit experimental, but enables a modern JS workflow and if you know and enjoy React workflows with HMR/fast-refresh, this should have you flying in no time!
+This package provides a development and build harness for creating React applications within Foundry. It also includes extensions of various Foundry VTT classes to support building React applications inside Foundry VTT. This is a bit experimental, but enables a modern JS workflow and if you know and enjoy React workflows with HMR/fast-refresh, this should have you flying in no time.
 
 **Disclaimers:**
-- ⚠️ Only tested against Foundry V13 at this point, v14 compatability testing coming soon (wanna try it out for me?)
-- ℹ️ Would love input if you're a Vite pro -- I have a suspicion devSetup could be a plugin, haven't had time to look into it.
+- Only tested against Foundry v13
+- Not a Foundry module, but a build dependency to add to your module's build workflow and dev setup
+- Relies on Vitejs building.
+- TypeScript friendly!
 
 ## Installation
 
@@ -159,143 +157,96 @@ const off = contextConnector.onUpdate(handleUpdate);
 
 ## Development setup with Vite
 
-For a fast dev loop with React Fast Refresh (HMR) inside Foundry, you split your module into **two entry points** and let a Vite dev server serve them:
-
-- `src/main.ts` — your **real app** entry (registers hooks, sheets, etc.). This is what gets bundled for production.
-- `src/main.js` — a tiny **dev-only shim** that calls `devSetup`, which injects the React Refresh runtime and then loads `src/main.ts` over HMR.
-
-The trick that ties it together: your manifest's `esmodules` points at `dist/main.js`. In a production build that's the bundled app. In development, the Vite dev server is configured so that the same `/modules/<id>/dist/main.js` URL is served from `src/main.js` (the shim) — so **the manifest entry resolves to the dev shim while you develop, and to the real bundle once built.**
-
-### Directory structure
+For a fast dev loop with React Fast Refresh inside Foundry, add the `foundry-vtt-react/vite` plugin. Your manifest's `esmodules` points at `dist/main.js`: in production that's your built bundle, and in dev the plugin's middleware serves that same URL with the Fast Refresh preamble + a dynamic import of your real entry — so there's no shim file and no hand-written Vite config to maintain.
 
 ```text
 my-module/
-├─ module.json          # manifest → esmodules: ["dist/main.js"]
-├─ package.json
+├─ module.json          # esmodules: ["dist/main.js"]
 ├─ vite.config.ts
-├─ src/
-│  ├─ main.js           # dev-only shim: calls devSetup() (served at dist/main.js in dev)
-│  ├─ main.ts           # real app entry: Hooks, registerSheet, … (build input)
-│  └─ MySheetApp.tsx    # your React component(s)
-└─ dist/                # build output (gitignored); created by `vite build`
+└─ src/
+   ├─ main.ts           # real entry: Hooks, registerSheet, … (build input)
+   └─ MySheetApp.tsx    # your React component(s)
 ```
 
-### Steps
+**1. Add the plugin** — it derives everything from your `module.json` `id`:
 
-**1. Manifest — point** `esmodules` **at the built path.**
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import foundryReact from "foundry-vtt-react/vite";
 
-```jsonc
-// module.json
-{
-  "id": "my-module",
-  "esmodules": ["dist/main.js"],
-  "styles": ["dist/main.css"],
-  "compatibility": { "minimum": "13", "verified": "13" }
-}
+export default defineConfig({ plugins: [react(), foundryReact()] });
 ```
 
-**2. Real app entry (**`src/main.ts`**)** — your normal module bootstrap:
+**2. Add scripts** — `"dev": "vite"` for the HMR server, `"build": "vite build"` for production.
 
-```ts
-import MyActorSheet from "./MyActorSheet";
+**3. Make the module visible to Foundry** — symlink (or copy) your module folder into Foundry's `Data/modules/`. With Docker, mount it instead:
 
-foundry.helpers.Hooks.once("ready", () => {
-  foundry.documents.collections.Actors.registerSheet("my-module", MyActorSheet, {
-    types: ["character"],
-    makeDefault: true,
-  });
-});
-```
+> ```yaml
+> foundry:
+>   image: felddy/foundryvtt:13
+>   volumes:
+>     - /path/to/my-module:/data/Data/modules/my-module
+> ```
 
-**3. Dev-only shim (**`src/main.js`**)** — calls `devSetup` with your module id and the path to the real entry:
+**4. Run it** — start Foundry (`:30000`), then `npm run dev` and open the Vite server (`:30001`). Edits to your components hot-reload. For production, `npm run build` ships `dist/`; the dev middleware isn't involved.
 
-```js
-import { id as APP_ID } from "../module.json";
-import { devSetup } from "foundry-vtt-react";
+`vite` and `@vitejs/plugin-react` are **optional peer dependencies** — needed only for this plugin, not the runtime classes (you already have them for any React + Vite setup).
 
-// Loads @react-refresh + src/main.ts (served at dist/main.ts) with HMR.
-devSetup(APP_ID, "dist/main.ts");
-```
+### Plugin options
+
+All options are optional:
+
+| Option          | Default                                                    | Description                                                              |
+| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `appId`         | the `id` read from `./module.json`                         | Your module's `id`. Used to build served paths and the proxy rule.       |
+| `entry`         | `"src/main.ts"`                                            | Your real app entry / build input, relative to the project root.         |
+| `foundryUrl`    | `"http://localhost:30000"`                                 | The local Foundry server that non-bundle requests are proxied to.        |
+| `port`          | `30001`                                                    | The Vite dev server port.                                                |
+| `manifestEntry` | basename of `module.json` `esmodules[0]`, else `"main.js"` | The bundle filename Foundry requests (where the dev preamble is served). |
 
-**4. Vite config** — serve `src/` at the manifest's `dist` path and proxy everything else to Foundry:
+### What it expands to
+
+For a module whose `id` is `my-module`, `foundryReact()` contributes the Vite config you'd otherwise hand-write — each value applied only when you haven't set it yourself, so your own config always wins:
 
 ```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import path from "path";
-import { id as APP_ID } from "./module.json";
-
-export default defineConfig({
-  plugins: [react()],
-  root: "src/",
-  // Serve src/ under the path the manifest references, so
-  // /modules/<id>/dist/main.js resolves to src/main.js (the shim),
-  // and /modules/<id>/dist/main.ts resolves to src/main.ts (the app).
-  base: `/modules/${APP_ID}/dist`,
+{
+  base: "/modules/my-module/dist",
+  root: "src",
+  // react/react-dom forced to a single copy — without this, a linked or git-installed
+  // foundry-vtt-react pulls a second React and every hook throws "Invalid hook call".
+  resolve: { dedupe: ["react", "react-dom"] },
   server: {
     port: 30001,
     proxy: {
-      // Everything that isn't your dev bundle goes to the Foundry server.
-      [`^(?!/modules/${APP_ID}/dist)`]: "http://localhost:30000/",
+      "^(?!/modules/my-module/dist)": "http://localhost:30000", // non-bundle requests → Foundry
       "/socket.io": { target: "ws://localhost:30000", ws: true },
     },
   },
   build: {
-    outDir: path.resolve(__dirname, "dist"),
+    outDir: "<root>/dist",
     emptyOutDir: true,
     rollupOptions: {
-      input: path.resolve(__dirname, "src/main.ts"), // build the real entry
+      input: "<root>/src/main.ts", // your `entry`
       output: { entryFileNames: "[name].js", assetFileNames: "[name].[ext]", format: "es" },
     },
   },
-});
-```
-
-**5. Scripts (**`package.json`**):**
-
-```jsonc
-{
-  "scripts": {
-    "dev": "vite",          // dev server with HMR
-    "build": "vite build"   // produces dist/main.js for production
-  }
 }
 ```
 
-**6. Make the module visible to Foundry** — symlink (or copy) your module folder into your Foundry data `Data/modules/` directory so Foundry can read `module.json`.
-
-> If you run foundry in docker like me, you can simply mount your local module volume into the docker foundry's modules folder like:
->
-> ```
-> foundry:
->     image: felddy/foundryvtt:13
->     hostname: localhost
->     volumes:
->       - /path/to/my-module:/data/Data/modules/my-module
-> ```
-
-**7. Run it.** Start Foundry (port `30000`), then `npm run dev` and open the Vite server (e.g. `http://localhost:30001`). Foundry loads your module; the manifest's `dist/main.js` is served from `src/main.js`, `devSetup` boots React Refresh, and edits to your components hot-reload.
+In dev it also serves the manifest URL (`/modules/my-module/dist/main.js`) with the module that replaces the old `src/main.js` shim:
 
-> For production, run `npm run build` and ship `dist/` — `dist/main.js` is now the bundled app, and `devSetup` is not involved.
-
-### `devSetup` reference
-
-```ts
-devSetup(appId: string, entrypoint: string): void
+```js
+// Fast Refresh preamble (reused from @vitejs/plugin-react; base derived from your config)
+import { injectIntoGlobalHook } from "/modules/my-module/dist/@react-refresh";
+injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+import("/modules/my-module/dist/main.ts"); // dynamic, so the preamble runs first
 ```
 
-
-| Parameter    | Description                                                                                                            |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `appId`      | Your module's `id` (from `module.json`). Used to build the served paths and to namespace the injected `<script>` tags. |
-| `entrypoint` | Path to your real app entry, relative to the module root (e.g. `dist/main.ts`), as served by the Vite dev server.      |
-
-
-It injects (idempotently — safe to call more than once):
-
-- A `<script type="module">` preamble that wires up the React Refresh global hooks, loading `@react-refresh` from `/modules/<appId>/dist/@react-refresh`.
-- A `<script type="module" src="/modules/<appId>/<entrypoint>">` that loads your app.
+> **Migrating from `devSetup`:** `devSetup` is **deprecated**. Delete your `src/main.js` shim and the hand-written `base`/`server`/`build` config, then add `foundryReact()` — it reproduces the same behavior, deriving the preamble and paths from your resolved Vite config.
 
 ## Exports
 

package/dist/{chunk-U6WX7YSY.mjs → chunk-7ZJUEWDX.mjs}

@@ -40,4 +40,4 @@ function devSetup(appId, entrypoint) {
 export {
   devSetup
 };
-//# sourceMappingURL=chunk-U6WX7YSY.mjs.map
+//# sourceMappingURL=chunk-7ZJUEWDX.mjs.map

package/dist/chunk-7ZJUEWDX.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../lib/util/logger.ts","../lib/util/dev-setup.ts"],"sourcesContent":["const logger =\n  (namespace: string): ((message: string) => void) =>\n  (message: string) => {\n    console.log(`%c[foundry-vtt-react][${namespace}]`, \"color: tomato;\", message);\n  };\n\nexport default logger;\n","import logger from \"../util/logger.js\";\nconst log = logger(\"dev-setup\");\n\n/**\n * devSetup.js\n *\n * Utility function to set up development environment for React applications in Foundry VTT. Used in conjunction\n * with a Vite development server, this function injects necessary scripts to enable React Fast Refresh and loads\n * the React application entrypoint.\n *\n * @deprecated Use the `foundry-vtt-react/vite` plugin instead. It derives the refresh preamble and paths\n * from your Vite config (no hand-maintained paths) and serves the dev entry via dev-server middleware, so\n * the `src/main.js` shim that calls `devSetup` is no longer needed. This function will be removed in a future major.\n *\n * @param {string} appId - The application ID used to construct module paths, typically the `id` value in `module.json`.\n * @param {string} entrypoint - The path to the React application entrypoint script relative to the module root. This should match\n *                             the entrypoint defined in the Vite configuration.\n */\nexport function devSetup(appId: string, entrypoint: string) {\n  const refreshScriptId = `foundry-react-refresh-script-${appId}`;\n\n  if (document.getElementById(refreshScriptId)) {\n    log(\"Script tag already exists, not adding again\");\n    return;\n  } else {\n    log(\"Adding script tag for react refresh\");\n\n    const scriptInner = `\n      import { injectIntoGlobalHook } from \"/modules/${appId}/dist/@react-refresh\";\n      injectIntoGlobalHook(window);\n      window.$RefreshReg$ = () => {};\n      window.$RefreshSig$ = () => (type) => type;\n  `;\n\n    const tag = document.createElement(\"script\");\n    tag.type = \"module\";\n    tag.id = refreshScriptId;\n    tag.innerHTML = scriptInner;\n    document.head.prepend(tag);\n  }\n\n  const devEntrypointId = `foundry-react-dev-entrypoint-${appId}`;\n  if (document.getElementById(devEntrypointId)) {\n    log(\"Dev entrypoint script tag already exists, not adding again\");\n    return;\n  } else {\n    const mainScript = document.createElement(\"script\");\n    mainScript.type = \"module\";\n    mainScript.src = `/modules/${appId}${entrypoint.startsWith(\"/\") ? \"\" : \"/\"}${entrypoint}`;\n    document.body.appendChild(mainScript);\n  }\n}\n"],"mappings":";AAAA,IAAM,SACJ,CAAC,cACD,CAAC,YAAoB;AACnB,UAAQ,IAAI,yBAAyB,SAAS,KAAK,kBAAkB,OAAO;AAC9E;AAEF,IAAO,iBAAQ;;;ACLf,IAAM,MAAM,eAAO,WAAW;AAiBvB,SAAS,SAAS,OAAe,YAAoB;AAC1D,QAAM,kBAAkB,gCAAgC,KAAK;AAE7D,MAAI,SAAS,eAAe,eAAe,GAAG;AAC5C,QAAI,6CAA6C;AACjD;AAAA,EACF,OAAO;AACL,QAAI,qCAAqC;AAEzC,UAAM,cAAc;AAAA,uDAC+B,KAAK;AAAA;AAAA;AAAA;AAAA;AAMxD,UAAM,MAAM,SAAS,cAAc,QAAQ;AAC3C,QAAI,OAAO;AACX,QAAI,KAAK;AACT,QAAI,YAAY;AAChB,aAAS,KAAK,QAAQ,GAAG;AAAA,EAC3B;AAEA,QAAM,kBAAkB,gCAAgC,KAAK;AAC7D,MAAI,SAAS,eAAe,eAAe,GAAG;AAC5C,QAAI,4DAA4D;AAChE;AAAA,EACF,OAAO;AACL,UAAM,aAAa,SAAS,cAAc,QAAQ;AAClD,eAAW,OAAO;AAClB,eAAW,MAAM,YAAY,KAAK,GAAG,WAAW,WAAW,GAAG,IAAI,KAAK,GAAG,GAAG,UAAU;AACvF,aAAS,KAAK,YAAY,UAAU;AAAA,EACtC;AACF;","names":[]}

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   devSetup
-} from "./chunk-U6WX7YSY.mjs";
+} from "./chunk-7ZJUEWDX.mjs";
 
 // lib/context-connector.ts
 var ContextConnector = class _ContextConnector extends EventTarget {

package/dist/util/dev-setup.d.mts

@@ -5,6 +5,10 @@
  * with a Vite development server, this function injects necessary scripts to enable React Fast Refresh and loads
  * the React application entrypoint.
  *
+ * @deprecated Use the `foundry-vtt-react/vite` plugin instead. It derives the refresh preamble and paths
+ * from your Vite config (no hand-maintained paths) and serves the dev entry via dev-server middleware, so
+ * the `src/main.js` shim that calls `devSetup` is no longer needed. This function will be removed in a future major.
+ *
  * @param {string} appId - The application ID used to construct module paths, typically the `id` value in `module.json`.
  * @param {string} entrypoint - The path to the React application entrypoint script relative to the module root. This should match
  *                             the entrypoint defined in the Vite configuration.

package/dist/util/dev-setup.mjs

@@ -1,6 +1,6 @@
 import {
   devSetup
-} from "../chunk-U6WX7YSY.mjs";
+} from "../chunk-7ZJUEWDX.mjs";
 export {
   devSetup
 };

package/dist/vite/index.d.mts

@@ -0,0 +1,38 @@
+import { Plugin } from 'vite';
+
+/** Options for the `foundry-vtt-react` Vite plugin. All optional; Foundry-friendly defaults fill in. */
+interface FoundryReactOptions {
+    /** Module `id`. Defaults to the `id` in `./module.json`. */
+    appId?: string;
+    /** App entry / build input, relative to the project root. Default `"src/main.ts"`. */
+    entry?: string;
+    /** Foundry server to proxy non-bundle requests to. Default `"http://localhost:30000"`. */
+    foundryUrl?: string;
+    /** Dev server port. Default `30001`. */
+    port?: number;
+    /** Bundle filename Foundry requests. Defaults to the basename of `esmodules[0]`, else `"main.js"`. */
+    manifestEntry?: string;
+}
+/**
+ * Read the Fast Refresh preamble template from `@vitejs/plugin-react` (its source of truth).
+ * Lazy import, never static: a static one couples us to plugin-react's internal-API version.
+ * plugin-react is required for the dev server, so a missing dep throws naturally here. `??` covers
+ * both export shapes (named pre-v6, default-export property since).
+ */
+declare function loadPreambleTemplate(): Promise<string>;
+/**
+ * Vite plugin wiring a React module into a local Foundry VTT instance: owns the Foundry-specific
+ * config (`base`, `root`, `server.proxy`, `build`, react dedupe — only where you haven't set it)
+ * and serves a Fast Refresh preamble at the manifest URL so Foundry boots with HMR, no shim file.
+ *
+ * @example
+ * export default defineConfig({ plugins: [react(), foundryReact()] });
+ */
+declare function foundryReact(options?: FoundryReactOptions): Plugin;
+/**
+ * Preamble (base-substituted) + a **dynamic** import of the real entry. Dynamic is required: a
+ * static `import` hoists above `injectIntoGlobalHook(window)` and breaks Fast Refresh.
+ */
+declare function buildDevModule(base: string, entryUrl: string, preambleTemplate: string): string;
+
+export { type FoundryReactOptions, buildDevModule, foundryReact as default, loadPreambleTemplate };

package/dist/vite/index.mjs

@@ -0,0 +1,93 @@
+// lib/vite/index.ts
+import { readFileSync } from "fs";
+import { basename, resolve } from "path";
+var PLUGIN_NAME = "vite-plugin-foundry-react";
+async function loadPreambleTemplate() {
+  const mod = await import("@vitejs/plugin-react");
+  return mod.default?.preambleCode ?? mod.preambleCode;
+}
+function readManifest(root) {
+  try {
+    return JSON.parse(readFileSync(resolve(root, "module.json"), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function foundryReact(options = {}) {
+  let base = "";
+  let entryUrl = "";
+  let manifestEntry = "";
+  let foundryUrl = "";
+  return {
+    name: PLUGIN_NAME,
+    config(userConfig) {
+      const root = userConfig.root ? resolve(process.cwd(), userConfig.root) : process.cwd();
+      const manifest = readManifest(process.cwd());
+      const appId = options.appId ?? manifest?.id;
+      if (!appId) {
+        throw new Error(
+          `[${PLUGIN_NAME}] Could not determine appId. Pass { appId } to the plugin, or run from a directory containing a module.json with an "id" field.`
+        );
+      }
+      const entry = options.entry ?? "src/main.ts";
+      foundryUrl = options.foundryUrl ?? "http://localhost:30000";
+      const port = options.port ?? 30001;
+      manifestEntry = options.manifestEntry ?? (manifest?.esmodules?.[0] ? basename(manifest.esmodules[0]) : "main.js");
+      base = `/modules/${appId}/dist`;
+      entryUrl = `${base}/${basename(entry)}`;
+      const proxy = {
+        [`^(?!${base})`]: foundryUrl,
+        // anything but the dev bundle → Foundry
+        "/socket.io": { target: foundryUrl.replace(/^http/, "ws"), ws: true }
+      };
+      const next = {};
+      if (userConfig.base == null) next.base = base;
+      if (userConfig.root == null) next.root = "src";
+      next.server = {
+        port: userConfig.server?.port ?? port,
+        proxy: { ...proxy, ...userConfig.server?.proxy }
+      };
+      next.build = {
+        outDir: userConfig.build?.outDir ?? resolve(root, "dist"),
+        emptyOutDir: userConfig.build?.emptyOutDir ?? true,
+        rollupOptions: {
+          input: userConfig.build?.rollupOptions?.input ?? resolve(root, entry),
+          output: userConfig.build?.rollupOptions?.output ?? {
+            entryFileNames: "[name].js",
+            assetFileNames: "[name].[ext]",
+            format: "es"
+          }
+        }
+      };
+      const dedupe = ["react", "react-dom"].filter((d) => !userConfig.resolve?.dedupe?.includes(d));
+      if (dedupe.length) next.resolve = { dedupe };
+      return next;
+    },
+    async configureServer(server) {
+      const manifestUrl = `${base}/${manifestEntry}`;
+      const preambleTemplate = await loadPreambleTemplate();
+      const body = buildDevModule(base, entryUrl, preambleTemplate);
+      server.middlewares.use((req, res, next) => {
+        const url = req.url?.split("?")[0];
+        if (url !== manifestUrl) return next();
+        res.setHeader("Content-Type", "text/javascript");
+        res.end(body);
+      });
+      server.config.logger.info(
+        `  ${PLUGIN_NAME} serving dev entry at ${manifestUrl} (proxying to ${foundryUrl})`
+      );
+    }
+  };
+}
+function buildDevModule(base, entryUrl, preambleTemplate) {
+  const baseWithSlash = base.endsWith("/") ? base : `${base}/`;
+  return `${preambleTemplate.replace("__BASE__", baseWithSlash)}
+import(${JSON.stringify(entryUrl)});
+`;
+}
+export {
+  buildDevModule,
+  foundryReact as default,
+  loadPreambleTemplate
+};
+//# sourceMappingURL=index.mjs.map

package/dist/vite/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../lib/vite/index.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { basename, resolve } from \"node:path\";\nimport type { Plugin, ProxyOptions, UserConfig } from \"vite\";\n\n/** Options for the `foundry-vtt-react` Vite plugin. All optional; Foundry-friendly defaults fill in. */\nexport interface FoundryReactOptions {\n  /** Module `id`. Defaults to the `id` in `./module.json`. */\n  appId?: string;\n  /** App entry / build input, relative to the project root. Default `\"src/main.ts\"`. */\n  entry?: string;\n  /** Foundry server to proxy non-bundle requests to. Default `\"http://localhost:30000\"`. */\n  foundryUrl?: string;\n  /** Dev server port. Default `30001`. */\n  port?: number;\n  /** Bundle filename Foundry requests. Defaults to the basename of `esmodules[0]`, else `\"main.js\"`. */\n  manifestEntry?: string;\n}\n\nconst PLUGIN_NAME = \"vite-plugin-foundry-react\";\n\n/**\n * Read the Fast Refresh preamble template from `@vitejs/plugin-react` (its source of truth).\n * Lazy import, never static: a static one couples us to plugin-react's internal-API version.\n * plugin-react is required for the dev server, so a missing dep throws naturally here. `??` covers\n * both export shapes (named pre-v6, default-export property since).\n */\nexport async function loadPreambleTemplate(): Promise<string> {\n  const mod: any = await import(\"@vitejs/plugin-react\");\n  return mod.default?.preambleCode ?? mod.preambleCode;\n}\n\nfunction readManifest(root: string): { id?: string; esmodules?: string[] } | null {\n  try {\n    return JSON.parse(readFileSync(resolve(root, \"module.json\"), \"utf-8\"));\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Vite plugin wiring a React module into a local Foundry VTT instance: owns the Foundry-specific\n * config (`base`, `root`, `server.proxy`, `build`, react dedupe — only where you haven't set it)\n * and serves a Fast Refresh preamble at the manifest URL so Foundry boots with HMR, no shim file.\n *\n * @example\n * export default defineConfig({ plugins: [react(), foundryReact()] });\n */\nexport default function foundryReact(options: FoundryReactOptions = {}): Plugin {\n  let base = \"\";\n  let entryUrl = \"\";\n  let manifestEntry = \"\";\n  let foundryUrl = \"\";\n\n  return {\n    name: PLUGIN_NAME,\n\n    config(userConfig): UserConfig {\n      const root = userConfig.root ? resolve(process.cwd(), userConfig.root) : process.cwd();\n      const manifest = readManifest(process.cwd());\n\n      const appId = options.appId ?? manifest?.id;\n      if (!appId) {\n        throw new Error(\n          `[${PLUGIN_NAME}] Could not determine appId. Pass { appId } to the plugin, ` +\n            `or run from a directory containing a module.json with an \"id\" field.`,\n        );\n      }\n\n      const entry = options.entry ?? \"src/main.ts\";\n      foundryUrl = options.foundryUrl ?? \"http://localhost:30000\";\n      const port = options.port ?? 30001;\n      manifestEntry =\n        options.manifestEntry ?? (manifest?.esmodules?.[0] ? basename(manifest.esmodules[0]) : \"main.js\");\n\n      base = `/modules/${appId}/dist`;\n      entryUrl = `${base}/${basename(entry)}`;\n\n      const proxy: Record<string, string | ProxyOptions> = {\n        [`^(?!${base})`]: foundryUrl, // anything but the dev bundle → Foundry\n        \"/socket.io\": { target: foundryUrl.replace(/^http/, \"ws\"), ws: true },\n      };\n\n      // Only fill what the user hasn't set, so their config always wins.\n      const next: UserConfig = {};\n      if (userConfig.base == null) next.base = base;\n      if (userConfig.root == null) next.root = \"src\";\n      next.server = {\n        port: userConfig.server?.port ?? port,\n        proxy: { ...proxy, ...userConfig.server?.proxy },\n      };\n      next.build = {\n        outDir: userConfig.build?.outDir ?? resolve(root, \"dist\"),\n        emptyOutDir: userConfig.build?.emptyOutDir ?? true,\n        rollupOptions: {\n          input: userConfig.build?.rollupOptions?.input ?? resolve(root, entry),\n          output: userConfig.build?.rollupOptions?.output ?? {\n            entryFileNames: \"[name].js\",\n            assetFileNames: \"[name].[ext]\",\n            format: \"es\",\n          },\n        },\n      };\n\n      // Force a single react/react-dom — a linked/git-installed copy otherwise duplicates React\n      // (\"Invalid hook call\"). Append only what the user hasn't (Vite concatenates dedupe lists).\n      const dedupe = [\"react\", \"react-dom\"].filter((d) => !userConfig.resolve?.dedupe?.includes(d));\n      if (dedupe.length) next.resolve = { dedupe };\n\n      return next;\n    },\n\n    async configureServer(server) {\n      const manifestUrl = `${base}/${manifestEntry}`;\n      const preambleTemplate = await loadPreambleTemplate();\n      const body = buildDevModule(base, entryUrl, preambleTemplate);\n\n      // Serve the preamble + dynamic entry import at the manifest URL (replaces the dev shim file).\n      server.middlewares.use((req, res, next) => {\n        const url = req.url?.split(\"?\")[0];\n        if (url !== manifestUrl) return next();\n\n        res.setHeader(\"Content-Type\", \"text/javascript\");\n        res.end(body);\n      });\n\n      server.config.logger.info(\n        `  ${PLUGIN_NAME} serving dev entry at ${manifestUrl} (proxying to ${foundryUrl})`,\n      );\n    },\n  };\n}\n\n/**\n * Preamble (base-substituted) + a **dynamic** import of the real entry. Dynamic is required: a\n * static `import` hoists above `injectIntoGlobalHook(window)` and breaks Fast Refresh.\n */\nexport function buildDevModule(base: string, entryUrl: string, preambleTemplate: string): string {\n  // plugin-react's `__BASE__` expects Vite's normalized base (trailing slash).\n  const baseWithSlash = base.endsWith(\"/\") ? base : `${base}/`;\n  return `${preambleTemplate.replace(\"__BASE__\", baseWithSlash)}\\nimport(${JSON.stringify(entryUrl)});\\n`;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foundry-vtt-react",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Extensions of various FoundryVTT classes to support React applications.",
   "packageManager": "pnpm@10.30.3",
   "main": "dist/index.mjs",
@@ -13,6 +13,10 @@
     "./dev-setup": {
       "types": "./dist/util/dev-setup.d.mts",
       "import": "./dist/util/dev-setup.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.mts",
+      "import": "./dist/vite/index.mjs"
     }
   },
   "files": [
@@ -21,6 +25,7 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
+    "prepare": "tsup",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [],
@@ -35,13 +40,25 @@
     "url": "https://github.com/tasandberg/foundry-vtt-react/issues"
   },
   "devDependencies": {
+    "@vitejs/plugin-react": "^6.0.2",
     "fvtt-types": "^13",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16"
   },
   "peerDependencies": {
+    "@vitejs/plugin-react": ">=4",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "@vitejs/plugin-react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@types/react": "^19.2.5",

package/dist/chunk-U6WX7YSY.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../lib/util/logger.ts","../lib/util/dev-setup.ts"],"sourcesContent":["const logger =\n  (namespace: string): ((message: string) => void) =>\n  (message: string) => {\n    console.log(`%c[foundry-vtt-react][${namespace}]`, \"color: tomato;\", message);\n  };\n\nexport default logger;\n","import logger from \"../util/logger.js\";\nconst log = logger(\"dev-setup\");\n\n/**\n * devSetup.js\n *\n * Utility function to set up development environment for React applications in Foundry VTT. Used in conjunction\n * with a Vite development server, this function injects necessary scripts to enable React Fast Refresh and loads\n * the React application entrypoint.\n *\n * @param {string} appId - The application ID used to construct module paths, typically the `id` value in `module.json`.\n * @param {string} entrypoint - The path to the React application entrypoint script relative to the module root. This should match\n *                             the entrypoint defined in the Vite configuration.\n */\nexport function devSetup(appId: string, entrypoint: string) {\n  const refreshScriptId = `foundry-react-refresh-script-${appId}`;\n\n  if (document.getElementById(refreshScriptId)) {\n    log(\"Script tag already exists, not adding again\");\n    return;\n  } else {\n    log(\"Adding script tag for react refresh\");\n\n    const scriptInner = `\n      import { injectIntoGlobalHook } from \"/modules/${appId}/dist/@react-refresh\";\n      injectIntoGlobalHook(window);\n      window.$RefreshReg$ = () => {};\n      window.$RefreshSig$ = () => (type) => type;\n  `;\n\n    const tag = document.createElement(\"script\");\n    tag.type = \"module\";\n    tag.id = refreshScriptId;\n    tag.innerHTML = scriptInner;\n    document.head.prepend(tag);\n  }\n\n  const devEntrypointId = `foundry-react-dev-entrypoint-${appId}`;\n  if (document.getElementById(devEntrypointId)) {\n    log(\"Dev entrypoint script tag already exists, not adding again\");\n    return;\n  } else {\n    const mainScript = document.createElement(\"script\");\n    mainScript.type = \"module\";\n    mainScript.src = `/modules/${appId}${entrypoint.startsWith(\"/\") ? \"\" : \"/\"}${entrypoint}`;\n    document.body.appendChild(mainScript);\n  }\n}\n"],"mappings":";AAAA,IAAM,SACJ,CAAC,cACD,CAAC,YAAoB;AACnB,UAAQ,IAAI,yBAAyB,SAAS,KAAK,kBAAkB,OAAO;AAC9E;AAEF,IAAO,iBAAQ;;;ACLf,IAAM,MAAM,eAAO,WAAW;AAavB,SAAS,SAAS,OAAe,YAAoB;AAC1D,QAAM,kBAAkB,gCAAgC,KAAK;AAE7D,MAAI,SAAS,eAAe,eAAe,GAAG;AAC5C,QAAI,6CAA6C;AACjD;AAAA,EACF,OAAO;AACL,QAAI,qCAAqC;AAEzC,UAAM,cAAc;AAAA,uDAC+B,KAAK;AAAA;AAAA;AAAA;AAAA;AAMxD,UAAM,MAAM,SAAS,cAAc,QAAQ;AAC3C,QAAI,OAAO;AACX,QAAI,KAAK;AACT,QAAI,YAAY;AAChB,aAAS,KAAK,QAAQ,GAAG;AAAA,EAC3B;AAEA,QAAM,kBAAkB,gCAAgC,KAAK;AAC7D,MAAI,SAAS,eAAe,eAAe,GAAG;AAC5C,QAAI,4DAA4D;AAChE;AAAA,EACF,OAAO;AACL,UAAM,aAAa,SAAS,cAAc,QAAQ;AAClD,eAAW,OAAO;AAClB,eAAW,MAAM,YAAY,KAAK,GAAG,WAAW,WAAW,GAAG,IAAI,KAAK,GAAG,GAAG,UAAU;AACvF,aAAS,KAAK,YAAY,UAAU;AAAA,EACtC;AACF;","names":[]}