feat(vite-plugin-mud): add MUD vite plugin (#3449)

Author: frolic

.changeset/khaki-panthers-collect.md

@@ -0,0 +1,32 @@
+---
+"vite-plugin-mud": patch
+---
+
+Initial release of Vite plugin for MUD projects.
+
+This will soon be included by default in MUD templates, but you can add to an existing MUD project with:
+
+```
+pnpm add -D vite@^6 vite-plugin-mud
+```
+
+And use like:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mud } from "vite-plugin-mud";
+
+export default defineConfig({
+  plugins: [mud({ worldsFile: "worlds.json" })],
+});
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["vite/client", "vite-plugin-mud/env"]
+  }
+}
+```

packages/vite-plugin-mud/README.md

@@ -0,0 +1,38 @@
+# vite-plugin-mud
+
+Vite plugin for MUD projects.
+
+This plugin will use your environment's `VITE_CHAIN_ID` to load the world deploy from your `worlds.json` file and provide it to your app via new environment variables.
+
+| Variable                        | Type                  | Description                                                |
+| ------------------------------- | --------------------- | ---------------------------------------------------------- |
+| `import.meta.env.CHAIN_ID`      | `number`              | The configured chain ID.                                   |
+| `import.meta.env.WORLD_ADDRESS` | `Hex \| undefined`    | The world contract address (if available).                 |
+| `import.meta.env.START_BLOCK`   | `bigint \| undefined` | The block number the world was deployed at (if available). |
+
+## Installation
+
+```
+pnpm add vite-plugin-mud
+```
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mud } from "vite-plugin-mud";
+
+export default defineConfig({
+  plugins: [mud({ worldsFile: "worlds.json" })],
+});
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["vite/client", "vite-plugin-mud/env"]
+  }
+}
+```

packages/vite-plugin-mud/env.d.ts

@@ -0,0 +1,5 @@
+interface ImportMetaEnv {
+  readonly CHAIN_ID: number;
+  readonly WORLD_ADDRESS: `0x${string}` | undefined;
+  readonly START_BLOCK: bigint | undefined;
+}

packages/vite-plugin-mud/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "vite-plugin-mud",
+  "version": "2.2.14",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latticexyz/mud.git",
+    "directory": "packages/vite-plugin-mud"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/exports/index.d.ts",
+      "default": "./dist/exports/index.js"
+    },
+    "./env": {
+      "types": "./env.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "index": [
+        "./dist/exports/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "env.d.ts"
+  ],
+  "scripts": {
+    "build": "pnpm run build:js",
+    "build:js": "tsup",
+    "clean": "pnpm run clean:js",
+    "clean:js": "shx rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^18.15.11",
+    "tsup": "^6.7.0",
+    "vite": "^6.0.7"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/vite-plugin-mud/src/exports/index.ts

@@ -0,0 +1 @@
+export { mud } from "../plugin";

packages/vite-plugin-mud/src/isReadable.ts

@@ -0,0 +1,10 @@
+import fs from "node:fs/promises";
+
+export async function isReadable(filename: string) {
+  try {
+    await fs.access(filename, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

packages/vite-plugin-mud/src/plugin.ts

@@ -0,0 +1,60 @@
+import { Plugin } from "vite";
+import { loadEnv } from "vite";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { isReadable } from "./isReadable";
+
+export function mud(opts: { worldsFile: string }): Plugin {
+  const rootDir = process.cwd();
+  const worldsFile = path.resolve(rootDir, opts.worldsFile);
+
+  return {
+    name: "vite-plugin-mud",
+    async config(config, { mode }) {
+      const env = Object.assign({}, process.env, loadEnv(mode, rootDir));
+      const chainId = Number(env.VITE_CHAIN_ID) || 31337;
+
+      config.define ??= {};
+      config.define["import.meta.env.CHAIN_ID"] = chainId;
+
+      if (!(await isReadable(worldsFile))) {
+        console.log("no worlds file");
+        return;
+      }
+
+      const worlds = JSON.parse(await fs.readFile(worldsFile, "utf-8")) as Partial<
+        Record<string, { address: `0x${string}`; blockNumber?: number }>
+      >;
+
+      const world = worlds[chainId];
+      if (world) {
+        config.define["import.meta.env.WORLD_ADDRESS"] = JSON.stringify(world.address);
+        config.define["import.meta.env.START_BLOCK"] = world.blockNumber != null ? `${world.blockNumber}n` : undefined;
+      } else {
+        console.log("no world deploy for chain ID", chainId);
+      }
+    },
+    configureServer(server) {
+      server.watcher.add(worldsFile);
+
+      server.watcher.on("add", handleFileChange);
+      server.watcher.on("change", handleFileChange);
+      server.watcher.on("unlink", handleFileChange);
+
+      // Wrap server restart in a delay to "debounce" so we
+      // only restart once after all file change emissions complete.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      function restart() {
+        clearTimeout(timer);
+        timer = setTimeout(() => server.restart(), 500);
+      }
+
+      function handleFileChange(filename: string) {
+        // TODO: check if this works on windows, as paths may have different separators
+        if (filename === worldsFile) {
+          restart();
+        }
+      }
+    },
+  };
+}

packages/vite-plugin-mud/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

packages/vite-plugin-mud/tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig((opts) => ({
+  entry: ["src/**"],
+  target: "esnext",
+  format: ["esm"],
+  sourcemap: true,
+  minify: true,
+  // don't generate DTS during watch mode because it's slow
+  // we're likely using TS source in this mode anyway
+  dts: !opts.watch,
+  // don't clean during watch mode to avoid removing
+  // previously-built DTS files, which other build tasks
+  // depend on
+  clean: !opts.watch,
+}));