aaex-file-router 1.3.0 → 1.3.1

package/README.md

@@ -2,10 +2,34 @@
 
 A file-based routing system for React projects that automatically generates routes from your file structure. Similar to Next.js App Router or Remix file conventions.
 
-## V. 1.3.0
-Routes are now able to be infinetly nested
-
-**Notice** Onlyt tested 3 levels deep but there is no reason i shouldnt work further
+## V. 1.3.1
+
+Routes are now able to be infinitely nested
+
+**Notice** Only tested 3 levels deep but there is no reason i shouldnt work further
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [1. Create your pages structure](#1-create-your-pages-structure)
+  - [2. Configure Vite](#2-configure-vite)
+  - [3. Use in your app](#3-use-in-your-app)
+    - [Using createBrowserRouter](#1-using-createbrowserrouter-recommended-for-most-users)
+    - [Using nested Route elements](#2-using-nested-route-elements)
+- [File Conventions](#file-conventions)
+- [Generated Routes File](#generated-routes-file)
+- [Route Resolution Examples](#route-resolution-examples)
+- [Layouts](#layouts)
+- [FileLink component](#filelink-component)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [How It Works](#how-it-works)
+- [Performance Considerations](#performance-considerations)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ## Features
 
@@ -44,7 +68,7 @@ src/pages/
 // vite.config.ts
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import { aaexFileRouter } from "aaex-file-router";
+import { aaexFileRouter } from "aaex-file-router/plugin";
 
 export default defineConfig({
   plugins: [
@@ -59,20 +83,66 @@ export default defineConfig({
 
 ### 3. Use in your app
 
+#### 1. Using createBrowserRouter (recommended for most users)
+
 ```typescript
-// src/main.tsx
-import React from "react";
-import ReactDOM from "react-dom/client";
-import { RouterProvider, createBrowserRouter } from "react-router-dom";
+// src/App.tsx
+import "./App.css";
 import routes from "./routes";
+import { createBrowserRouter, RouterProvider } from "react-router-dom";
+import { Suspense } from "react";
+
+function App() {
+  const router = createBrowserRouter(routes);
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <RouterProvider router={router} />
+    </Suspense>
+  );
+}
+
+export default App;
+```
+
+## **OR**
+
+### 2. using nested Route elements
 
-const router = createBrowserRouter(routes);
+**Note** I will probably create a custom route provider using this version later since this is the only solution that works with VITE-SSR if you wrap client in `<BrowserRouter/>` and server in `<StaticRouter/>`
+
+```tsx
+//src/App.tsx
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  type RouteObject,
+} from "react-router-dom";
+import routes from "./routes";
+import { Suspense } from "react";
+import "./App.css";
+
+//recursivly creates nested routes
+function createRoutes(route: RouteObject) {
+  return (
+    <Route key={route.path} path={route.path} element={route.element}>
+      {route.children?.map((child) => createRoutes(child))}
+    </Route>
+  );
+}
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Routes>{routes.map((route) => createRoutes(route))}</Routes>
+      </Suspense>
+    </BrowserRouter>
+  );
+}
 
-ReactDOM.createRoot(document.getElementById("root")!).render(
-  <React.StrictMode>
-    <RouterProvider router={router} />
-  </React.StrictMode>
-);
+export default App;
 ```
 
 ## File Conventions
@@ -106,14 +176,14 @@ export default function AdminLayout() {
 
 ### Slug files
 
-Filenames wrapper in hardbrackets `[filename]` will resolve to a dynamic route
+Filenames wrapper in square brackets `[filename]` will resolve to a dynamic route
 
 ```
-pages/test/[<filename>].tsx → "/test/:<filename>"
+src/pages/test/[<filename>].tsx → "/test/:<filename>"
 ```
 
 ```tsx
-//pages/test/[slug].tsx
+// src/pages/test/[slug].tsx
 
 import { useParams } from "react-router-dom";
 
@@ -165,20 +235,20 @@ export default routes;
 
 ## Route Resolution Examples
 
-| File Structure                      | Route Path           |
-| ----------------------------------- | -------------------- |
-| `pages/index.tsx`                   | `/`                  |
-| `pages/about.tsx`                   | `/about`             |
-| `pages/blog/index.tsx`              | `/blog`              |
-| `pages/blog/post.tsx`               | `/blog/post`         |
-| `pages/admin/layout.tsx` + children | `/admin/*` (grouped) |
+| File Structure                          | Route Path           |
+| --------------------------------------- | -------------------- |
+| `src/pages/index.tsx`                   | `/`                  |
+| `src/pages/about.tsx`                   | `/about`             |
+| `src/pages/blog/index.tsx`              | `/blog`              |
+| `src/pages/blog/post.tsx`               | `/blog/post`         |
+| `src/pages/admin/layout.tsx` + children | `/admin/*` (grouped) |
 
 ## Layouts
 
 Layouts wrap their child routes and provide shared UI:
 
 ```typescript
-// pages/dashboard/layout.tsx
+// src/pages/dashboard/layout.tsx
 import { Outlet } from "react-router-dom";
 
 export default function DashboardLayout() {
@@ -193,7 +263,7 @@ export default function DashboardLayout() {
 }
 ```
 
-All routes in `pages/dashboard/*` will render inside this layout.
+All routes in `src/pages/dashboard/*` will render inside this layout.
 
 ## FileLink component
 
@@ -215,7 +285,7 @@ export type FileRoutes = "/" | "test";
 ```
 
 ```tsx
-//src/pages/index.tsx
+// src/pages/index.tsx
 import { FileLink } from "aaex-file-router";
 import type { FileRoutes } from "../routeTypes";
 
@@ -225,7 +295,7 @@ export default function Home() {
       Hello Home!
       {/* FileRoutes is optional and not required it will work fine with any string if not passed */}
       <FileLink<FileRoutes> to="test">Test safe</FileLink>
-      //or //no type safety
+      {/* or without type safety */}
       <FileLink to="some-route">Non safe</FileLink>
     </>
   );
@@ -261,7 +331,7 @@ const routesCode = await generator.generateComponentsMap(fileData);
 Automatically watches for file changes and regenerates routes.
 
 ```typescript
-import { aaexFileRouter } from "aaex-file-router/core";
+import { aaexFileRouter } from "aaex-file-router/plugin";
 
 export default defineConfig({
   plugins: [

package/dist/core/index.d.ts

@@ -1,5 +1,3 @@
 export { FileScanner } from './FileScanner.js';
 export { RouteGenerator } from './RouteGenerator.js';
-export { aaexFileRouter } from '../plugin.js';
-export type { VitePluginOptions } from '../plugin.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/core/index.js

@@ -1,5 +1,4 @@
 export { FileScanner } from './FileScanner.js';
 export { RouteGenerator } from './RouteGenerator.js';
 // export type { FileData } from './core/types';
-export { aaexFileRouter } from '../plugin.js';
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,gDAAgD;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,gDAAgD"}

package/dist/plugin/index.d.ts

@@ -0,0 +1,3 @@
+export { aaexFileRouter } from '../plugin/plugin.js';
+export type { VitePluginOptions } from '../plugin/plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/plugin/index.js

@@ -0,0 +1,2 @@
+export { aaexFileRouter } from '../plugin/plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from "vite";
+export interface VitePluginOptions {
+    pagesDir?: string;
+    outputFile?: string;
+}
+/**
+ * Vite plugin that auto-generates routes when page files change
+ * Watches the pages directory and regenerates routes.ts on file create/delete
+ */
+export declare function aaexFileRouter(options?: VitePluginOptions): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/plugin/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAM9B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAmDtE"}

package/dist/plugin/plugin.js

@@ -0,0 +1,48 @@
+import { promises as fs } from "node:fs";
+import path from "path";
+import { FileScanner } from "../core/FileScanner.js";
+import { RouteGenerator } from "../core/RouteGenerator.js";
+/**
+ * Vite plugin that auto-generates routes when page files change
+ * Watches the pages directory and regenerates routes.ts on file create/delete
+ */
+export function aaexFileRouter(options = {}) {
+    const pagesDir = options.pagesDir || "./src/pages";
+    const outputFile = options.outputFile || "./src/routes.ts";
+    let scanner;
+    let generator;
+    return {
+        name: "aaex-file-router",
+        apply: "serve", // Only run in dev mode
+        configResolved() {
+            scanner = new FileScanner(pagesDir);
+            generator = new RouteGenerator();
+        },
+        async configureServer(server) {
+            // Watch the pages directory for changes
+            server.watcher.add(path.resolve(process.cwd(), pagesDir));
+            server.watcher.on("all", async (event, filePath) => {
+                // Only regenerate on file add/unlink events
+                if (event === "add" || event === "unlink") {
+                    try {
+                        console.log(`📄 [aaex-file-router] ${event}: ${filePath}`);
+                        // Regenerate routes
+                        scanner = new FileScanner(pagesDir);
+                        generator = new RouteGenerator();
+                        const fileData = await scanner.get_file_data();
+                        const routesCode = await generator.generateRoutesFile(fileData);
+                        const routesType = await generator.generateRoutesTypeDef(fileData);
+                        // Write routes file
+                        await fs.writeFile(outputFile, routesCode, "utf-8");
+                        await fs.writeFile("src/routeTypes.ts", routesType, "utf-8");
+                        console.log(`✅ [aaex-file-router] Routes regenerated at ${outputFile}`);
+                    }
+                    catch (error) {
+                        console.error("❌ [aaex-file-router] Error regenerating routes:", error);
+                    }
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAO3D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,UAA6B,EAAE;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,aAAa,CAAC;IACnD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAE3D,IAAI,OAAoB,CAAC;IACzB,IAAI,SAAyB,CAAC;IAE9B,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,OAAO,EAAE,uBAAuB;QAEvC,cAAc;YACZ,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;YACpC,SAAS,GAAG,IAAI,cAAc,EAAE,CAAC;QACnC,CAAC;QAED,KAAK,CAAC,eAAe,CAAC,MAAM;YAC1B,wCAAwC;YACxC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;YAE1D,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjD,4CAA4C;gBAC5C,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC1C,IAAI,CAAC;wBACH,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,KAAK,QAAQ,EAAE,CAAC,CAAC;wBAE3D,oBAAoB;wBACpB,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;wBACpC,SAAS,GAAG,IAAI,cAAc,EAAE,CAAC;wBAEjC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC;wBAC/C,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;wBAChE,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;wBAEnE,oBAAoB;wBACpB,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;wBACpD,MAAM,EAAE,CAAC,SAAS,CAAC,mBAAmB,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;wBAE7D,OAAO,CAAC,GAAG,CACT,8CAA8C,UAAU,EAAE,CAC3D,CAAC;oBACJ,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,OAAO,CAAC,KAAK,CACX,iDAAiD,EACjD,KAAK,CACN,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aaex-file-router",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "A file-based routing system for React projects that automatically generates routes from your file structure. Similar to Next.js App Router or Remix file conventions.",
   "main": "dist/index.js",
   "scripts": {
@@ -16,7 +16,8 @@
 
   "exports":{
       ".": "./dist/index.js",
-      "./core": "./dist/core/index.js"
+      "./core": "./dist/core/index.js",
+      "./plugin": "./dist/plugin/index.js"
   },
   "author": "TmRAaEx",
   "license": "MIT",