foundry-vtt-react 0.1.0 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Sandberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,47 @@
 # Foundry VTT React
 
-This package provides extensions of various Foundry VTT classes to support React applications development within Foundry.
+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
+- 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
 
-Currently supported FoundryVTT classes:
+```bash
+npm install foundry-vtt-react
+# or: pnpm add foundry-vtt-react
+```
+
+`react` and `react-dom` (v19) are peer dependencies — install them in your module if you haven't already:
+
+```bash
+npm install react react-dom
+```
 
-- `ReactApplicationV2`: A base application class for creating React-based applications in Foundry VTT.
-- `ReactActorSheetV2`: An actor sheet class that uses React for rendering the UI, allowing the React app to listen for changes to the document using the native ActoSheetV2 lifecycle events.
+## Supported Foundry classes
+
+- `ReactApplicationV2` — a base `ApplicationV2` that renders a React component instead of a Handlebars template.
+- `ReactActorSheetV2` — an `ActorSheetV2` that renders with React, letting your component react to document changes through the native sheet lifecycle.
+
+Both are produced by the same `ReactApplicationMixin`, so they share the options and lifecycle described below.
 
 ## Usage
 
-There are two important pieces to developing React applications in Foundry.
+There are two pieces to developing React applications in Foundry:
 
-1. Creating your ReactApplicationV2 instance and passing in your React component.
-2. Configuring ViteJS development server to work with your local FoundryVTT instance.
+1. Creating a React-powered application instance and passing in your React component.
+2. Configuring a Vite dev server to work with your local Foundry instance (see [Development setup](#development-setup-with-vite)).
 
-### Creating a ReactApplicationV2 Instance
+### Creating a ReactApplicationV2 instance
 
-To create a new React-powered Foundry application, you can instantiate the `ReactApplicationV2` class and provide your React component along with any initial properties and window options.
+Instantiate `ReactApplicationV2` with your React component plus any initial props and window options:
+
+```jsx
+import { ReactApplicationV2 } from "foundry-vtt-react";
 
-```javascript
 // Basic component
 function MyReactComponent(props) {
   return <div>Hello, {props.data}!</div>;
@@ -36,4 +57,205 @@ const app = new ReactApplicationV2({
 app.render(true);
 ```
 
-![alt text](assets/image.png)
+A React component rendered inside a Foundry application window
+
+**Constructor options**
+
+
+| Option         | Type                  | Description                                                                              |
+| -------------- | --------------------- | ---------------------------------------------------------------------------------------- |
+| `reactApp`     | `React.ComponentType` | The component mounted into the application window.                                       |
+| `initialProps` | `object` (optional)   | Props passed to `reactApp` on mount. Also reachable via `_prepareContext` (see below).   |
+| ...options     | `ApplicationV2`       | Any standard `ApplicationV2` options (`window`, `position`, `classes`, `actions`, etc.). |
+
+
+### Building a React actor sheet
+
+Subclass `ReactActorSheetV2`, set `reactApp`, and register it as the sheet for your actor type. Override `_prepareContext` to choose exactly which props your component receives — this is also where you hand your component the `[ContextConnector](#reacting-to-foundry-updates-with-contextconnector)` so it can subscribe to live document updates:
+
+```jsx
+import { ReactActorSheetV2 } from "foundry-vtt-react";
+import MySheetApp from "./MySheetApp";
+
+class MyActorSheet extends ReactActorSheetV2 {
+  reactApp = MySheetApp;
+
+  static DEFAULT_OPTIONS = {
+    window: { title: "My Sheet", resizable: true },
+    position: { width: 625, height: 750 },
+    classes: ["my-sheet"],
+  };
+
+  async _prepareContext(options) {
+    const context = await super._prepareContext(options);
+    // Pick the props your React app receives:
+    context.initialProps = {
+      actor: context.document,
+      source: context.source,
+      contextConnector: this.contextConnector, // for live updates
+    };
+    return context;
+  }
+}
+```
+
+Register it like any other sheet, e.g.:
+
+```js
+foundry.documents.collections.Actors.registerSheet("my-module", MyActorSheet, {
+  types: ["character"],
+  makeDefault: true,
+});
+```
+
+### Reacting to Foundry updates with ContextConnector
+
+Every React application instance owns a `ContextConnector` at `this.contextConnector`. On **every** render, the mixin calls `contextConnector.publishContext(context)` with the prepared context (which, for a sheet, includes the updated `document`). Pass the connector into your component (via `initialProps`, as shown above) and subscribe to those updates so React re-renders when the Foundry document changes.
+
+`onUpdate(callback)` returns a **disposer** function, ideal for `useEffect` cleanup:
+
+```jsx
+import { useEffect, useState } from "react";
+
+function MySheetApp({ actor: initialActor, contextConnector }) {
+  const [actor, setActor] = useState(initialActor);
+
+  useEffect(() => {
+    // Re-render whenever Foundry re-renders the sheet
+    const off = contextConnector.onUpdate(({ document }) => {
+      setActor(document);
+    });
+    return off; // unsubscribe on unmount
+  }, [contextConnector]);
+
+  return <h1>{actor.name}</h1>;
+}
+```
+
+You can debounce noisy update streams with Foundry's helper:
+
+```jsx
+const handleUpdate = foundry.utils.debounce(({ document }) => {
+  setActor(document);
+}, 200);
+const off = contextConnector.onUpdate(handleUpdate);
+```
+
+`ContextConnector<T>` **API**
+
+
+| Method                    | Returns      | Description                                                         |
+| ------------------------- | ------------ | ------------------------------------------------------------------- |
+| `onUpdate(cb)`            | `() => void` | Subscribe to context updates. Returns a disposer that unsubscribes. |
+| `tearDown(cb)`            | `void`       | Unsubscribe a callback previously passed to `onUpdate`.             |
+| `on(event, cb)`           | `() => void` | Subscribe to a custom event. Returns a disposer.                    |
+| `off(event, cb)`          | `void`       | Unsubscribe a callback from a custom event.                         |
+| `publishContext(context)` | `void`       | Emit a context update. Called for you by the mixin on each render.  |
+
+
+> Use the returned disposer **or** `tearDown(cb)` to clean up — either removes the listener.
+
+## Development setup with Vite
+
+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          # esmodules: ["dist/main.js"]
+├─ vite.config.ts
+└─ src/
+   ├─ main.ts           # real entry: Hooks, registerSheet, … (build input)
+   └─ MySheetApp.tsx    # your React component(s)
+```
+
+**1. Add the plugin** — it derives everything from your `module.json` `id`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import foundryReact from "foundry-vtt-react/vite";
+
+export default defineConfig({ plugins: [react(), foundryReact()] });
+```
+
+**2. Add scripts** — `"dev": "vite"` for the HMR server, `"build": "vite build"` for production.
+
+**3. Make the module visible to Foundry** — symlink (or copy) your module folder into Foundry's `Data/modules/`. With Docker, mount it instead:
+
+> ```yaml
+> foundry:
+>   image: felddy/foundryvtt:13
+>   volumes:
+>     - /path/to/my-module:/data/Data/modules/my-module
+> ```
+
+**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.
+
+`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).
+
+### 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). |
+
+### 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
+{
+  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: {
+      "^(?!/modules/my-module/dist)": "http://localhost:30000", // non-bundle requests → Foundry
+      "/socket.io": { target: "ws://localhost:30000", ws: true },
+    },
+  },
+  build: {
+    outDir: "<root>/dist",
+    emptyOutDir: true,
+    rollupOptions: {
+      input: "<root>/src/main.ts", // your `entry`
+      output: { entryFileNames: "[name].js", assetFileNames: "[name].[ext]", format: "es" },
+    },
+  },
+}
+```
+
+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:
+
+```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
+```
+
+> **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
+
+```js
+import {
+  ReactApplicationV2,
+  ReactActorSheetV2,
+  ContextConnector,
+  devSetup,
+} from "foundry-vtt-react";
+```
+

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.d.mts

@@ -1,12 +1,27 @@
 export { devSetup } from './util/dev-setup.mjs';
 
+/**
+ * Event-based bridge for pushing Foundry context updates into React.
+ *
+ * A `ReactApplicationMixin` instance creates one connector and calls
+ * {@link ContextConnector.publishContext} on every render. React components
+ * subscribe with {@link ContextConnector.onUpdate} to re-render on changes.
+ */
 declare class ContextConnector<T> extends EventTarget {
+    #private;
     static UPDATE: string;
-    constructor();
     publishContext(context: T): void;
-    on(event: string, callback: (data: T) => void): void;
-    onUpdate(callback: (data: T) => void): void;
-    tearDown(fn: (data: T) => void): void;
+    /**
+     * Subscribe to an event. Returns a disposer that removes the listener,
+     * convenient for React `useEffect` cleanup.
+     */
+    on(event: string, callback: (data: T) => void): () => void;
+    /** Subscribe to context updates. Returns a disposer. */
+    onUpdate(callback: (data: T) => void): () => void;
+    /** Remove a listener previously added with {@link on}. */
+    off(event: string, callback: (data: T) => void): void;
+    /** Remove a context-update listener previously added with {@link onUpdate}. */
+    tearDown(callback: (data: T) => void): void;
 }
 
 declare const ReactApplicationV2_base: {

package/dist/index.mjs

@@ -1,26 +1,48 @@
 import {
   devSetup
-} from "./chunk-U6WX7YSY.mjs";
+} from "./chunk-7ZJUEWDX.mjs";
 
 // lib/context-connector.ts
 var ContextConnector = class _ContextConnector extends EventTarget {
   static UPDATE = "contextUpdate";
-  constructor() {
-    super();
-  }
+  /**
+   * Maps each subscriber callback to the wrapper actually registered with
+   * `addEventListener`, so `off`/`tearDown` can remove it by the original
+   * callback reference.
+   */
+  #wrappers = /* @__PURE__ */ new Map();
   publishContext(context) {
-    this.dispatchEvent(new CustomEvent("contextUpdate", { detail: context }));
+    this.dispatchEvent(
+      new CustomEvent(_ContextConnector.UPDATE, { detail: context })
+    );
   }
+  /**
+   * Subscribe to an event. Returns a disposer that removes the listener,
+   * convenient for React `useEffect` cleanup.
+   */
   on(event, callback) {
-    this.addEventListener(event, (e) => {
-      callback(e.detail);
-    });
+    if (!this.#wrappers.has(callback)) {
+      const wrapper = (e) => callback(e.detail);
+      this.#wrappers.set(callback, wrapper);
+      this.addEventListener(event, wrapper);
+    }
+    return () => this.off(event, callback);
   }
+  /** Subscribe to context updates. Returns a disposer. */
   onUpdate(callback) {
-    this.on(_ContextConnector.UPDATE, callback);
+    return this.on(_ContextConnector.UPDATE, callback);
+  }
+  /** Remove a listener previously added with {@link on}. */
+  off(event, callback) {
+    const wrapper = this.#wrappers.get(callback);
+    if (wrapper) {
+      this.removeEventListener(event, wrapper);
+      this.#wrappers.delete(callback);
+    }
   }
-  tearDown(fn) {
-    this.removeEventListener(_ContextConnector.UPDATE, fn);
+  /** Remove a context-update listener previously added with {@link onUpdate}. */
+  tearDown(callback) {
+    this.off(_ContextConnector.UPDATE, callback);
   }
 };
 

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../lib/context-connector.ts","../lib/util/mount-app.tsx","../lib/react-application-mixin.ts","../lib/react-application-v2.ts","../lib/react-actor-sheet-v2.ts"],"sourcesContent":["export class ContextConnector<T> extends EventTarget {\n  static UPDATE = \"contextUpdate\";\n\n  constructor() {\n    super();\n  }\n\n  publishContext(context: T) {\n    this.dispatchEvent(new CustomEvent(\"contextUpdate\", { detail: context }));\n  }\n\n  on(event: string, callback: (data: T) => void) {\n    this.addEventListener(event, (e: CustomEventInit<T>) => {\n      callback(e.detail!);\n    });\n  }\n\n  onUpdate(callback: (data: T) => void) {\n    this.on(ContextConnector.UPDATE, callback);\n  }\n\n  tearDown(fn: (data: T) => void) {\n    this.removeEventListener(ContextConnector.UPDATE, fn as EventListener);\n  }\n}\n","import { createRoot } from \"react-dom/client\";\n\nexport function mountApp({\n  App,\n  element,\n  initialProps = {},\n  innerSelector,\n}: {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  App: React.ComponentType<any>;\n  element: Element;\n  initialProps?: {};\n  innerSelector: string;\n}) {\n  const root = createRoot(element);\n  root.render(\n    <div id={innerSelector}>\n      <App {...initialProps} />\n    </div>\n  );\n}\n","import { ContextConnector } from \"./context-connector\";\nimport { mountApp } from \"./util/mount-app\";\n\n/**\n * A mixin that integrates React components with Foundry VTT's Application class.\n * This mixin enables the use of React applications within Foundry VTT's application framework.\n *\n * @param superclass - The base class to extend, typically a Foundry VTT Application class\n * @returns A class that extends the superclass with React integration capabilities\n *\n * @remarks\n * This mixin provides the following features:\n * - Mounting React components within Foundry VTT applications\n * - Context management through ContextConnector\n * - Automatic cleanup and rendering lifecycle management\n * - Default window options for position and configuration\n *\n * @example\n * ```typescript\n * class MyReactApp extends ReactApplicationMixin(Application) {\n *   constructor(options) {\n *     super({\n *       reactApp: MyReactComponent,\n *       initialProps: { data: \"example\" },\n *       ...options\n *     });\n *   }\n * }\n * ```\n */\n\ntype ReactApplicationProps = {\n  reactApp: React.ComponentType<any>;\n  initialProps?: Record<string, any>;\n};\n\nfunction ReactApplicationMixin(Superclass: any) {\n  return class ReactApplication extends Superclass {\n    reactApp: React.ComponentType<any>;\n    uuid = foundry.utils.randomID(12);\n    rootId = `react-app-root-${this.uuid}`;\n    innerSelector = `react-application-inner-${this.rootId}`;\n    contextConnector: ContextConnector<any>;\n\n    static DEFAULT_OPTIONS = {\n      position: {\n        width: 400,\n        height: 300,\n      },\n      window: {\n        title: \"Hello React-powered Foundry applications\",\n        resizable: true,\n        minimizable: true,\n      },\n    };\n\n    initialProps = {};\n\n    constructor({ reactApp, initialProps, ...options }: ReactApplicationProps & any) {\n      super(options);\n      this.reactApp = reactApp;\n      this.contextConnector = new ContextConnector();\n      this.initialProps = initialProps || {};\n    }\n\n    get appIsRendered() {\n      return !!document.querySelector(`#${this.innerSelector}`);\n    }\n\n    async _onRender(context: any, options: any) {\n      await super._onRender(context, options);\n      const el = this.element.querySelectorAll(`#${this.rootId}`);\n\n      if (el && !this.appIsRendered) {\n        mountApp({\n          App: this.reactApp,\n          element: el[0],\n          initialProps: context.initialProps,\n          innerSelector: this.innerSelector,\n        });\n      }\n      this.contextConnector.publishContext(context);\n    }\n\n    _replaceHTML(result: HTMLElement, content: HTMLElement) {\n      if (!this.appIsRendered) {\n        content.appendChild(result);\n      }\n    }\n\n    async _prepareContext(options: any) {\n      const context = (await super._prepareContext(options)) as any;\n      context.initialProps = this.initialProps;\n      return context;\n    }\n\n    async _renderHTML() {\n      const tempEl = document.createElement(\"div\");\n      tempEl.id = this.rootId;\n      tempEl.innerHTML = `<span>Uh oh, something went wrong</span>`;\n      return tempEl;\n    }\n  };\n}\n\nexport default ReactApplicationMixin;\n","import ReactApplicationMixin from \"./react-application-mixin\";\n\n/**\n * A Foundry VTT Application class that integrates React components with the Foundry application framework.\n * Extends ApplicationV2 to provide seamless React app mounting and rendering capabilities.\n *\n * @class FoundryReactApplication\n * @extends foundry.applications.api.ApplicationV2\n *\n * @example\n * // Create a new React-powered Foundry application\n * const app = new FoundryReactApplication({\n *   reactApp: MyReactComponent,\n *   initialProps: { data: 'example' },\n *   window: { title: \"My React App\" },\n *   position: { width: 600, height: 400 }\n * });\n *\n * @property {React.Component} reactApp - The React component to be mounted\n * @property {string} template - Path to the Handlebars template for the application shell\n * @property {Object} initialProps - Initial properties passed to the React component\n * @property {string} rootId - ID added to the root element where the React app will be mounted\n */\nexport class ReactApplicationV2 extends ReactApplicationMixin(foundry.applications.api.ApplicationV2) {}\n","/**\n * A React-enabled version of Foundry VTT's ActorSheetV2 class.\n *\n * This class extends the core ActorSheetV2 functionality by applying the ReactApplicationMixin,\n * which enables React component rendering within the actor sheet application.\n *\n * @extends {foundry.applications.sheets.ActorSheetV2}\n * @mixes ReactApplicationMixin\n *\n * @example\n * ```typescript\n * class MyActorSheet extends ReactActorSheetV2 {\n *   // Your custom React-enabled actor sheet implementation\n * }\n * ```\n */\nimport ReactApplicationMixin from \"./react-application-mixin\";\n\nexport class ReactActorSheetV2 extends ReactApplicationMixin(foundry.applications.sheets.ActorSheetV2) {}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../lib/context-connector.ts","../lib/util/mount-app.tsx","../lib/react-application-mixin.ts","../lib/react-application-v2.ts","../lib/react-actor-sheet-v2.ts"],"sourcesContent":["/**\n * Event-based bridge for pushing Foundry context updates into React.\n *\n * A `ReactApplicationMixin` instance creates one connector and calls\n * {@link ContextConnector.publishContext} on every render. React components\n * subscribe with {@link ContextConnector.onUpdate} to re-render on changes.\n */\nexport class ContextConnector<T> extends EventTarget {\n  static UPDATE = \"contextUpdate\";\n\n  /**\n   * Maps each subscriber callback to the wrapper actually registered with\n   * `addEventListener`, so `off`/`tearDown` can remove it by the original\n   * callback reference.\n   */\n  #wrappers = new Map<(data: T) => void, EventListener>();\n\n  publishContext(context: T) {\n    this.dispatchEvent(\n      new CustomEvent(ContextConnector.UPDATE, { detail: context })\n    );\n  }\n\n  /**\n   * Subscribe to an event. Returns a disposer that removes the listener,\n   * convenient for React `useEffect` cleanup.\n   */\n  on(event: string, callback: (data: T) => void): () => void {\n    if (!this.#wrappers.has(callback)) {\n      const wrapper: EventListener = (e) =>\n        callback((e as CustomEvent<T>).detail);\n      this.#wrappers.set(callback, wrapper);\n      this.addEventListener(event, wrapper);\n    }\n    return () => this.off(event, callback);\n  }\n\n  /** Subscribe to context updates. Returns a disposer. */\n  onUpdate(callback: (data: T) => void): () => void {\n    return this.on(ContextConnector.UPDATE, callback);\n  }\n\n  /** Remove a listener previously added with {@link on}. */\n  off(event: string, callback: (data: T) => void) {\n    const wrapper = this.#wrappers.get(callback);\n    if (wrapper) {\n      this.removeEventListener(event, wrapper);\n      this.#wrappers.delete(callback);\n    }\n  }\n\n  /** Remove a context-update listener previously added with {@link onUpdate}. */\n  tearDown(callback: (data: T) => void) {\n    this.off(ContextConnector.UPDATE, callback);\n  }\n}\n","import { createRoot } from \"react-dom/client\";\n\nexport function mountApp({\n  App,\n  element,\n  initialProps = {},\n  innerSelector,\n}: {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  App: React.ComponentType<any>;\n  element: Element;\n  initialProps?: {};\n  innerSelector: string;\n}) {\n  const root = createRoot(element);\n  root.render(\n    <div id={innerSelector}>\n      <App {...initialProps} />\n    </div>\n  );\n}\n","import { ContextConnector } from \"./context-connector\";\nimport { mountApp } from \"./util/mount-app\";\n\n/**\n * A mixin that integrates React components with Foundry VTT's Application class.\n * This mixin enables the use of React applications within Foundry VTT's application framework.\n *\n * @param superclass - The base class to extend, typically a Foundry VTT Application class\n * @returns A class that extends the superclass with React integration capabilities\n *\n * @remarks\n * This mixin provides the following features:\n * - Mounting React components within Foundry VTT applications\n * - Context management through ContextConnector\n * - Automatic cleanup and rendering lifecycle management\n * - Default window options for position and configuration\n *\n * @example\n * ```typescript\n * class MyReactApp extends ReactApplicationMixin(Application) {\n *   constructor(options) {\n *     super({\n *       reactApp: MyReactComponent,\n *       initialProps: { data: \"example\" },\n *       ...options\n *     });\n *   }\n * }\n * ```\n */\n\ntype ReactApplicationProps = {\n  reactApp: React.ComponentType<any>;\n  initialProps?: Record<string, any>;\n};\n\nfunction ReactApplicationMixin(Superclass: any) {\n  return class ReactApplication extends Superclass {\n    reactApp: React.ComponentType<any>;\n    uuid = foundry.utils.randomID(12);\n    rootId = `react-app-root-${this.uuid}`;\n    innerSelector = `react-application-inner-${this.rootId}`;\n    contextConnector: ContextConnector<any>;\n\n    static DEFAULT_OPTIONS = {\n      position: {\n        width: 400,\n        height: 300,\n      },\n      window: {\n        title: \"Hello React-powered Foundry applications\",\n        resizable: true,\n        minimizable: true,\n      },\n    };\n\n    initialProps = {};\n\n    constructor({ reactApp, initialProps, ...options }: ReactApplicationProps & any) {\n      super(options);\n      this.reactApp = reactApp;\n      this.contextConnector = new ContextConnector();\n      this.initialProps = initialProps || {};\n    }\n\n    get appIsRendered() {\n      return !!document.querySelector(`#${this.innerSelector}`);\n    }\n\n    async _onRender(context: any, options: any) {\n      await super._onRender(context, options);\n      const el = this.element.querySelectorAll(`#${this.rootId}`);\n\n      if (el && !this.appIsRendered) {\n        mountApp({\n          App: this.reactApp,\n          element: el[0],\n          initialProps: context.initialProps,\n          innerSelector: this.innerSelector,\n        });\n      }\n      this.contextConnector.publishContext(context);\n    }\n\n    _replaceHTML(result: HTMLElement, content: HTMLElement) {\n      if (!this.appIsRendered) {\n        content.appendChild(result);\n      }\n    }\n\n    async _prepareContext(options: any) {\n      const context = (await super._prepareContext(options)) as any;\n      context.initialProps = this.initialProps;\n      return context;\n    }\n\n    async _renderHTML() {\n      const tempEl = document.createElement(\"div\");\n      tempEl.id = this.rootId;\n      tempEl.innerHTML = `<span>Uh oh, something went wrong</span>`;\n      return tempEl;\n    }\n  };\n}\n\nexport default ReactApplicationMixin;\n","import ReactApplicationMixin from \"./react-application-mixin\";\n\n/**\n * A Foundry VTT Application class that integrates React components with the Foundry application framework.\n * Extends ApplicationV2 to provide seamless React app mounting and rendering capabilities.\n *\n * @class FoundryReactApplication\n * @extends foundry.applications.api.ApplicationV2\n *\n * @example\n * // Create a new React-powered Foundry application\n * const app = new FoundryReactApplication({\n *   reactApp: MyReactComponent,\n *   initialProps: { data: 'example' },\n *   window: { title: \"My React App\" },\n *   position: { width: 600, height: 400 }\n * });\n *\n * @property {React.Component} reactApp - The React component to be mounted\n * @property {string} template - Path to the Handlebars template for the application shell\n * @property {Object} initialProps - Initial properties passed to the React component\n * @property {string} rootId - ID added to the root element where the React app will be mounted\n */\nexport class ReactApplicationV2 extends ReactApplicationMixin(foundry.applications.api.ApplicationV2) {}\n","/**\n * A React-enabled version of Foundry VTT's ActorSheetV2 class.\n *\n * This class extends the core ActorSheetV2 functionality by applying the ReactApplicationMixin,\n * which enables React component rendering within the actor sheet application.\n *\n * @extends {foundry.applications.sheets.ActorSheetV2}\n * @mixes ReactApplicationMixin\n *\n * @example\n * ```typescript\n * class MyActorSheet extends ReactActorSheetV2 {\n *   // Your custom React-enabled actor sheet implementation\n * }\n * ```\n */\nimport ReactApplicationMixin from \"./react-application-mixin\";\n\nexport class ReactActorSheetV2 extends ReactApplicationMixin(foundry.applications.sheets.ActorSheetV2) {}\n"],"mappings":"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","names":[]}

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.0",
+  "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,19 +25,40 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
+    "prepare": "tsup",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "author": "Tim Sandberg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tasandberg/foundry-vtt-react.git"
+  },
+  "homepage": "https://github.com/tasandberg/foundry-vtt-react#readme",
+  "bugs": {
+    "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":[]}