@troyio/vite-file-router 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# vite-file-router
+
+A Vite plugin that generates a route tree from a file-based page directory.
+
+## Install
+
+```sh
+npm install @troyio/vite-file-router
+```
+
+Vite is a peer dependency and must also be installed in your project.
+
+## Configure
+
+```ts
+import { defineConfig } from "vite";
+import { routes } from "@troyio/vite-file-router";
+
+export default defineConfig({
+  plugins: [routes()],
+});
+```
+
+By default, the plugin scans `src/pages`. Pass a path relative to the Vite
+project root to use another directory:
+
+```ts
+plugins: [routes("src/routes")];
+```
+
+Each `page.jsx` or `page.tsx` becomes a route page, and each `layout.jsx` or
+`layout.tsx` becomes a lazy layout for its directory. Directories become nested
+routes. Add a `loading.jsx` or `loading.tsx` to provide a Suspense fallback for
+that directory's page and nested routes; a nested loading file provides a more
+specific fallback. Each file must default-export a React component. If both
+extensions exist for the same component, `.tsx` takes precedence. For example:
+
+```text
+src/pages/
+  layout.jsx
+  loading.jsx
+  page.jsx
+  users/
+    loading.tsx
+    page.tsx
+    [id]/
+      page.tsx
+```
+
+Dynamic segments such as `[id]` become `:id`; catch-all segments such as
+`[...slug]` become `*`.
+
+Import the generated route configuration from the `virtual:routes` module in
+your application:
+
+```ts
+import { routes } from "virtual:routes";
+```
+
+The virtual module exports a `routes` array with lazy-loaded page and layout
+components.
+
+## Build
+
+```sh
+npm run build
+```

package/dist/generator.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from "./scanner";
+export type GeneratedRoutes = {
+    imports: string[];
+    routes: string;
+};
+export declare function generate(node: Node, root?: boolean): GeneratedRoutes;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function routes(directory?: string): Plugin;

package/dist/index.js

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import { genArrayFromRaw, genObjectFromRaw } from "knitwork";
+import { normalizePath } from "vite";
+// src/scanner.ts
+function scan(directory) {
+	const node = {
+		name: path.basename(directory),
+		directory,
+		children: []
+	};
+	if (!fs.existsSync(directory)) return node;
+	const entries = fs.readdirSync(directory, { withFileTypes: true });
+	for (const entry of entries) {
+		const file = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			node.children.push(scan(file));
+			continue;
+		}
+		const match = /^(page|layout|loading)\.(jsx|tsx)$/.exec(entry.name);
+		if (!match) continue;
+		const [, name, extension] = match;
+		const key = name;
+		if (!node[key] || extension === "tsx") node[key] = file;
+	}
+	return node;
+}
+// src/generator.ts
+function getRoutePath(directory) {
+	const segment = path.basename(directory);
+	if (segment.startsWith("[...") && segment.endsWith("]")) return "*";
+	return segment.replace(/^\[(.+)\]$/, ":$1");
+}
+function generateImport(file) {
+	return `async () => ({
+    Component: (await import(${JSON.stringify(normalizePath(file))})).default
+  })`;
+}
+function generateLazyComponent(file) {
+	return `lazy(() => import(${JSON.stringify(normalizePath(file))}))`;
+}
+function generateNode(node, root, context, inheritedBoundary) {
+	const route = {};
+	const hasBoundary = inheritedBoundary || Boolean(node.loading);
+	if (!root) route.path = JSON.stringify(getRoutePath(node.directory));
+	let loadingComponent;
+	if (node.loading) {
+		loadingComponent = `Loading${context.nextLoadingId++}`;
+		context.loadingImports.push(`import ${loadingComponent} from ${JSON.stringify(normalizePath(node.loading))};`);
+		context.hasBoundaries = true;
+	}
+	if (loadingComponent) {
+		const child = node.layout ? generateLazyComponent(node.layout) : "Outlet";
+		route.Component = `createBoundary(${loadingComponent}, ${child})`;
+	} else if (node.layout) {
+		if (hasBoundary) route.Component = generateLazyComponent(node.layout);
+		else route.lazy = generateImport(node.layout);
+	}
+	const children = [];
+	if (node.page) {
+		const page = hasBoundary ? {
+			index: "true",
+			Component: generateLazyComponent(node.page)
+		} : {
+			index: "true",
+			lazy: generateImport(node.page)
+		};
+		children.push(genObjectFromRaw(page));
+	}
+	for (const child of node.children) children.push(generateNode(child, false, context, hasBoundary));
+	if (children.length) route.children = genArrayFromRaw(children);
+	return genObjectFromRaw(route);
+}
+function generate(node, root = false) {
+	const context = {
+		loadingImports: [],
+		nextLoadingId: 0,
+		hasBoundaries: false
+	};
+	const routes = generateNode(node, root, context, false);
+	const imports = [...context.loadingImports];
+	if (context.hasBoundaries) imports.unshift(`import { createElement, lazy, Suspense } from "react";`, `import { Outlet } from "react-router";`, `function createBoundary(Fallback, Component) {
+  return function RouteBoundary() {
+    return createElement(
+      Suspense,
+      { fallback: createElement(Fallback) },
+      createElement(Component),
+    );
+  };
+}`);
+	return {
+		imports,
+		routes
+	};
+}
+// src/index.ts
+var MODULE_ID = "virtual:routes";
+var RESOLVED_ID = `\0${MODULE_ID}`;
+function routes(directory = "src/pages") {
+	let root = "";
+	function execute() {
+		const generated = generate(scan(root), true);
+		return `
+      ${generated.imports.join("\n")}
+      export const routes = ${genArrayFromRaw([generated.routes])};
+    `;
+	}
+	return {
+		name: "routes",
+		configResolved(config) {
+			root = path.resolve(config.root, directory);
+		},
+		resolveId: (id) => id === MODULE_ID ? RESOLVED_ID : void 0,
+		load: (id) => id === RESOLVED_ID ? execute() : void 0,
+		configureServer: (server) => {
+			server.watcher.add(root);
+			server.watcher.on("all", (event, file) => {
+				if (![
+					"add",
+					"unlink",
+					"addDir",
+					"unlinkDir",
+					"change"
+				].includes(event)) return;
+				const location = path.resolve(file);
+				if (location !== root && !location.startsWith(root + path.sep)) return;
+				const module = server.moduleGraph.getModuleById(RESOLVED_ID);
+				if (module) server.moduleGraph.invalidateModule(module);
+				server.ws.send({ type: "full-reload" });
+			});
+		}
+	};
+}
+export { routes };

package/dist/scanner.d.ts

@@ -0,0 +1,9 @@
+export type Node = {
+    name: string;
+    directory: string;
+    page?: string;
+    layout?: string;
+    loading?: string;
+    children: Node[];
+};
+export declare function scan(directory: string): Node;

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@troyio/vite-file-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "File-system routing plugin for Vite",
+  "type": "module",
+  "private": false,
+  "keywords": [
+    "vite",
+    "react",
+    "routing",
+    "react-router"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "main": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "lint": "eslint src vite.config.ts",
+    "prepublish": "pnpm build"
+  },
+  "dependencies": {
+    "knitwork": "^1.3.0",
+    "react-router": "^8.5.1",
+    "vite-file-router": "link:"
+  },
+  "peerDependencies": {
+    "react": ">=19.2.7",
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.2",
+    "eslint": "^10.14.0",
+    "globals": "^17.14.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.5"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="./virtual-routes.d.ts" />
+
+export { routes } from "../dist/index.js";

package/types/virtual-routes.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:routes" {
+  import type { RouteObject } from "react-router";
+  export const routes: RouteObject[];
+}