vite-plugin-app-boundaries 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# vite-plugin-app-boundaries
+
+Enforce **strict architectural boundaries** between application folders
+in Vite.
+
+This plugin prevents one app (e.g. `Front`) from importing code from
+another app (e.g. `Pro`) at **build time and dev time**, not just via
+linting.
+
+If a boundary is violated, **Vite errors immediately**.
+
+------------------------------------------------------------------------
+
+## Why this exists
+
+Lint rules are easy to bypass. Aliases hide real paths. Large multi-front apps rot over time.
+
+This plugin makes architecture **non-negotiable** by enforcing rules
+directly in Vite's module resolution graph.
+
+------------------------------------------------------------------------
+
+## Features
+
+-   ✅ Enforce boundaries between **any number of apps**
+-   ✅ Errors in **dev AND build**
+-   ✅ Alias-aware (uses Vite's resolver)
+-   ✅ Configurable allowlists
+-   ✅ Zero runtime cost
+-   ✅ Works with Vite 5 / 6 / 7
+
+------------------------------------------------------------------------
+
+## Example use case
+
+``` txt
+resources/js/Apps/
+├── Front/
+├── Pro/
+└── Shared/
+```
+
+Rules: 
+- ❌ `Front` cannot import from `Pro` 
+- ❌ `Pro` cannot import from `Front` 
+- ✅ Both can import from `Shared`
+
+------------------------------------------------------------------------
+
+## Installation
+
+``` bash
+npm install -D vite-plugin-app-boundaries
+```
+
+or
+
+``` bash
+pnpm add -D vite-plugin-app-boundaries
+```
+
+------------------------------------------------------------------------
+
+## Basic usage
+
+### `vite.config.ts`
+
+``` ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { enforceAppBoundaries } from "vite-plugin-app-boundaries";
+
+export default defineConfig({
+  plugins: [
+    enforceAppBoundaries({
+      root: "resources/js/Apps",
+
+      apps: {
+        Front: {
+          path: "Front",
+          allowImportsFrom: ["Shared"],
+        },
+
+        Pro: {
+          path: "Pro",
+          allowImportsFrom: ["Shared"],
+        },
+
+        Shared: {
+          path: "Shared",
+        },
+      },
+    }),
+
+    react(),
+  ],
+});
+```
+
+------------------------------------------------------------------------
+
+## What happens on violation
+
+``` ts
+// Apps/Front/pages/welcome.tsx
+import Editor from "@/Apps/Pro/components/editorjs";
+```
+
+⬇️
+
+``` txt
+🚫 App boundary violation
+
+Importer:
+.../Apps/Front/pages/welcome.tsx
+(app: Front)
+
+Imported:
+.../Apps/Pro/components/editorjs.tsx
+(app: Pro)
+
+Allowed imports for Front:
+Shared
+```
+
+Vite stops immediately.
+
+------------------------------------------------------------------------
+
+## Configuration reference
+
+### `root`
+
+Root directory that contains all apps.
+
+``` ts
+root: "resources/js/Apps"
+```
+
+------------------------------------------------------------------------
+
+### `apps`
+
+Each app has:
+
+-   `path`: folder name under `root`
+-   `allowImportsFrom`: optional list of app names it may import from
+
+``` ts
+apps: {
+  Front: {
+    path: "Front",
+    allowImportsFrom: ["Shared"],
+  },
+
+  Admin: {
+    path: "Admin",
+    allowImportsFrom: ["Shared", "Pro"],
+  },
+}
+```
+
+------------------------------------------------------------------------
+
+### `debug` (optional)
+
+Enable verbose logging to see exactly how Vite resolves imports.
+
+``` ts
+enforceAppBoundaries({
+  debug: true,
+  ...
+});
+```
+
+Useful when diagnosing aliases or unexpected resolution.
+
+------------------------------------------------------------------------
+
+## ESLint mirror rules (recommended)
+
+This plugin enforces boundaries at **build time**.\
+For **editor errors**, mirror the rules using ESLint.
+
+### Install
+
+``` bash
+npm install -D eslint-plugin-boundaries
+```
+
+### Example `.eslintrc.cjs`
+
+``` js
+module.exports = {
+  plugins: ["boundaries"],
+
+  settings: {
+    "boundaries/include": ["resources/js/**/*"],
+
+    "boundaries/elements": [
+      { type: "front", pattern: "resources/js/Apps/Front/**" },
+      { type: "pro", pattern: "resources/js/Apps/Pro/**" },
+      { type: "shared", pattern: "resources/js/Apps/Shared/**" },
+    ],
+  },
+
+  rules: {
+    "boundaries/element-types": [
+      "error",
+      {
+        default: "disallow",
+        rules: [
+          { from: "front", allow: ["shared"] },
+          { from: "pro", allow: ["shared"] },
+          { from: "shared", allow: ["shared"] },
+        ],
+      },
+    ],
+  },
+};
+```
+
+------------------------------------------------------------------------
+
+## What this plugin does NOT do
+
+-   ❌ It does not replace ESLint
+-   ❌ It does not rewrite imports
+-   ❌ It does not enforce runtime isolation
+
+Recommended setup: 
+
+- **This plugin** → build-time enforcement 
+- **ESLint boundaries rules** → editor feedback
+
+------------------------------------------------------------------------
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,69 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+
+//#region src/plugin.ts
+function normalize(p) {
+	return p.split(node_path.default.sep).join("/");
+}
+function enforceAppBoundaries(options) {
+	const root = normalize(node_path.default.resolve(options.root));
+	const apps = Object.entries(options.apps).map(([name, cfg]) => ({
+		name,
+		root: normalize(node_path.default.join(root, cfg.path)),
+		allow: new Set(cfg.allowImportsFrom ?? [])
+	}));
+	function findApp(file) {
+		return apps.find((app) => file.startsWith(app.root));
+	}
+	return {
+		name: "vite-plugin-app-boundaries",
+		enforce: "pre",
+		async resolveId(source, importer) {
+			if (!importer) return null;
+			const importerPath = normalize(importer);
+			if (!importerPath.startsWith(root)) return null;
+			const importerApp = findApp(importerPath);
+			if (!importerApp) return null;
+			const resolved = await this.resolve(source, importer, { skipSelf: true });
+			if (!resolved) return null;
+			const resolvedPath = normalize(resolved.id);
+			if (!resolvedPath.startsWith(root)) return null;
+			const importedApp = findApp(resolvedPath);
+			if (!importedApp) return null;
+			if (importedApp.name === importerApp.name) return null;
+			if (importerApp.allow.has(importedApp.name)) return null;
+			throw new Error(`🚫 App boundary violation\n\n${importerPath}\n→ ${resolvedPath}`);
+		}
+	};
+}
+
+//#endregion
+exports.enforceAppBoundaries = enforceAppBoundaries;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["path"],"sources":["../src/plugin.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport type { AppBoundariesOptions } from \"./types\";\n\nfunction normalize(p: string) {\n  return p.split(path.sep).join(\"/\");\n}\n\nexport function enforceAppBoundaries(\n  options: AppBoundariesOptions\n): Plugin {\n  const root = normalize(path.resolve(options.root));\n\n  const apps = Object.entries(options.apps).map(\n    ([name, cfg]) => ({\n      name,\n      root: normalize(path.join(root, cfg.path)),\n      allow: new Set(cfg.allowImportsFrom ?? []),\n    })\n  );\n\n  function findApp(file: string) {\n    return apps.find(app => file.startsWith(app.root));\n  }\n\n  function log(...args: any[]) {\n    if (options.debug) {\n      console.log(\"[vite-app-boundaries]\", ...args);\n    }\n  }\n\n  return {\n    name: \"vite-plugin-app-boundaries\",\n    enforce: \"pre\",\n\n    async resolveId(source, importer) {\n      if (!importer) return null;\n\n      const importerPath = normalize(importer);\n      if (!importerPath.startsWith(root)) return null;\n\n      const importerApp = findApp(importerPath);\n      if (!importerApp) return null;\n\n      const resolved = await this.resolve(source, importer, {\n        skipSelf: true,\n      });\n\n      if (!resolved) return null;\n\n      const resolvedPath = normalize(resolved.id);\n      if (!resolvedPath.startsWith(root)) return null;\n\n      const importedApp = findApp(resolvedPath);\n      if (!importedApp) return null;\n\n      if (importedApp.name === importerApp.name) return null;\n      if (importerApp.allow.has(importedApp.name)) return null;\n\n      throw new Error(\n        `🚫 App boundary violation\\n\\n${importerPath}\\n→ ${resolvedPath}`\n      );\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAIA,SAAS,UAAU,GAAW;AAC5B,QAAO,EAAE,MAAMA,kBAAK,IAAI,CAAC,KAAK,IAAI;;AAGpC,SAAgB,qBACd,SACQ;CACR,MAAM,OAAO,UAAUA,kBAAK,QAAQ,QAAQ,KAAK,CAAC;CAElD,MAAM,OAAO,OAAO,QAAQ,QAAQ,KAAK,CAAC,KACvC,CAAC,MAAM,UAAU;EAChB;EACA,MAAM,UAAUA,kBAAK,KAAK,MAAM,IAAI,KAAK,CAAC;EAC1C,OAAO,IAAI,IAAI,IAAI,oBAAoB,EAAE,CAAC;EAC3C,EACF;CAED,SAAS,QAAQ,MAAc;AAC7B,SAAO,KAAK,MAAK,QAAO,KAAK,WAAW,IAAI,KAAK,CAAC;;AASpD,QAAO;EACL,MAAM;EACN,SAAS;EAET,MAAM,UAAU,QAAQ,UAAU;AAChC,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,eAAe,UAAU,SAAS;AACxC,OAAI,CAAC,aAAa,WAAW,KAAK,CAAE,QAAO;GAE3C,MAAM,cAAc,QAAQ,aAAa;AACzC,OAAI,CAAC,YAAa,QAAO;GAEzB,MAAM,WAAW,MAAM,KAAK,QAAQ,QAAQ,UAAU,EACpD,UAAU,MACX,CAAC;AAEF,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,eAAe,UAAU,SAAS,GAAG;AAC3C,OAAI,CAAC,aAAa,WAAW,KAAK,CAAE,QAAO;GAE3C,MAAM,cAAc,QAAQ,aAAa;AACzC,OAAI,CAAC,YAAa,QAAO;AAEzB,OAAI,YAAY,SAAS,YAAY,KAAM,QAAO;AAClD,OAAI,YAAY,MAAM,IAAI,YAAY,KAAK,CAAE,QAAO;AAEpD,SAAM,IAAI,MACR,gCAAgC,aAAa,MAAM,eACpD;;EAEJ"}

package/dist/index.d.cts

@@ -0,0 +1,18 @@
+import { Plugin } from "vite";
+
+//#region src/types.d.ts
+type AppConfig = {
+  path: string;
+  allowImportsFrom?: string[];
+};
+type AppBoundariesOptions = {
+  root: string;
+  apps: Record<string, AppConfig>;
+  debug?: boolean;
+};
+//#endregion
+//#region src/plugin.d.ts
+declare function enforceAppBoundaries(options: AppBoundariesOptions): Plugin;
+//#endregion
+export { type AppBoundariesOptions, type AppConfig, enforceAppBoundaries };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import { Plugin } from "vite";
+
+//#region src/types.d.ts
+type AppConfig = {
+  path: string;
+  allowImportsFrom?: string[];
+};
+type AppBoundariesOptions = {
+  root: string;
+  apps: Record<string, AppConfig>;
+  debug?: boolean;
+};
+//#endregion
+//#region src/plugin.d.ts
+declare function enforceAppBoundaries(options: AppBoundariesOptions): Plugin;
+//#endregion
+export { type AppBoundariesOptions, type AppConfig, enforceAppBoundaries };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,41 @@
+import path from "node:path";
+
+//#region src/plugin.ts
+function normalize(p) {
+	return p.split(path.sep).join("/");
+}
+function enforceAppBoundaries(options) {
+	const root = normalize(path.resolve(options.root));
+	const apps = Object.entries(options.apps).map(([name, cfg]) => ({
+		name,
+		root: normalize(path.join(root, cfg.path)),
+		allow: new Set(cfg.allowImportsFrom ?? [])
+	}));
+	function findApp(file) {
+		return apps.find((app) => file.startsWith(app.root));
+	}
+	return {
+		name: "vite-plugin-app-boundaries",
+		enforce: "pre",
+		async resolveId(source, importer) {
+			if (!importer) return null;
+			const importerPath = normalize(importer);
+			if (!importerPath.startsWith(root)) return null;
+			const importerApp = findApp(importerPath);
+			if (!importerApp) return null;
+			const resolved = await this.resolve(source, importer, { skipSelf: true });
+			if (!resolved) return null;
+			const resolvedPath = normalize(resolved.id);
+			if (!resolvedPath.startsWith(root)) return null;
+			const importedApp = findApp(resolvedPath);
+			if (!importedApp) return null;
+			if (importedApp.name === importerApp.name) return null;
+			if (importerApp.allow.has(importedApp.name)) return null;
+			throw new Error(`🚫 App boundary violation\n\n${importerPath}\n→ ${resolvedPath}`);
+		}
+	};
+}
+
+//#endregion
+export { enforceAppBoundaries };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/plugin.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport type { AppBoundariesOptions } from \"./types\";\n\nfunction normalize(p: string) {\n  return p.split(path.sep).join(\"/\");\n}\n\nexport function enforceAppBoundaries(\n  options: AppBoundariesOptions\n): Plugin {\n  const root = normalize(path.resolve(options.root));\n\n  const apps = Object.entries(options.apps).map(\n    ([name, cfg]) => ({\n      name,\n      root: normalize(path.join(root, cfg.path)),\n      allow: new Set(cfg.allowImportsFrom ?? []),\n    })\n  );\n\n  function findApp(file: string) {\n    return apps.find(app => file.startsWith(app.root));\n  }\n\n  function log(...args: any[]) {\n    if (options.debug) {\n      console.log(\"[vite-app-boundaries]\", ...args);\n    }\n  }\n\n  return {\n    name: \"vite-plugin-app-boundaries\",\n    enforce: \"pre\",\n\n    async resolveId(source, importer) {\n      if (!importer) return null;\n\n      const importerPath = normalize(importer);\n      if (!importerPath.startsWith(root)) return null;\n\n      const importerApp = findApp(importerPath);\n      if (!importerApp) return null;\n\n      const resolved = await this.resolve(source, importer, {\n        skipSelf: true,\n      });\n\n      if (!resolved) return null;\n\n      const resolvedPath = normalize(resolved.id);\n      if (!resolvedPath.startsWith(root)) return null;\n\n      const importedApp = findApp(resolvedPath);\n      if (!importedApp) return null;\n\n      if (importedApp.name === importerApp.name) return null;\n      if (importerApp.allow.has(importedApp.name)) return null;\n\n      throw new Error(\n        `🚫 App boundary violation\\n\\n${importerPath}\\n→ ${resolvedPath}`\n      );\n    },\n  };\n}\n"],"mappings":";;;AAIA,SAAS,UAAU,GAAW;AAC5B,QAAO,EAAE,MAAM,KAAK,IAAI,CAAC,KAAK,IAAI;;AAGpC,SAAgB,qBACd,SACQ;CACR,MAAM,OAAO,UAAU,KAAK,QAAQ,QAAQ,KAAK,CAAC;CAElD,MAAM,OAAO,OAAO,QAAQ,QAAQ,KAAK,CAAC,KACvC,CAAC,MAAM,UAAU;EAChB;EACA,MAAM,UAAU,KAAK,KAAK,MAAM,IAAI,KAAK,CAAC;EAC1C,OAAO,IAAI,IAAI,IAAI,oBAAoB,EAAE,CAAC;EAC3C,EACF;CAED,SAAS,QAAQ,MAAc;AAC7B,SAAO,KAAK,MAAK,QAAO,KAAK,WAAW,IAAI,KAAK,CAAC;;AASpD,QAAO;EACL,MAAM;EACN,SAAS;EAET,MAAM,UAAU,QAAQ,UAAU;AAChC,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,eAAe,UAAU,SAAS;AACxC,OAAI,CAAC,aAAa,WAAW,KAAK,CAAE,QAAO;GAE3C,MAAM,cAAc,QAAQ,aAAa;AACzC,OAAI,CAAC,YAAa,QAAO;GAEzB,MAAM,WAAW,MAAM,KAAK,QAAQ,QAAQ,UAAU,EACpD,UAAU,MACX,CAAC;AAEF,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,eAAe,UAAU,SAAS,GAAG;AAC3C,OAAI,CAAC,aAAa,WAAW,KAAK,CAAE,QAAO;GAE3C,MAAM,cAAc,QAAQ,aAAa;AACzC,OAAI,CAAC,YAAa,QAAO;AAEzB,OAAI,YAAY,SAAS,YAAY,KAAM,QAAO;AAClD,OAAI,YAAY,MAAM,IAAI,YAAY,KAAK,CAAE,QAAO;AAEpD,SAAM,IAAI,MACR,gCAAgC,aAAa,MAAM,eACpD;;EAEJ"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "vite-plugin-app-boundaries",
+  "version": "0.1.0",
+  "description": "Enforce architectural boundaries between app folders in Vite",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "tsdown": "^0.19.0-beta.1",
+    "vitest": "^1.2.0",
+    "vite": "^7.0.0"
+  },
+  "license": "MIT"
+}