ts-file-router 6.0.0 → 6.0.2

package/README.md

@@ -1,19 +1,20 @@
 # 📦 ts-file-router
 
-A lightweight TypeScript filesystem router generator.  
-Automatically scans folders and outputs a clean, structured `routes.ts` tree ready for dynamic imports (e.g., `React.lazy`).
+A lightweight **filesystem router generator** for TypeScript projects. Automatically scans your folder structure and generates a clean, typed `routes.ts` tree ready for dynamic imports (e.g., `React.lazy`).
 
 ---
 
 ## ✨ Features
 
-- 🔍 Recursive folder scanning
-- 📄 Auto-generated `routes.ts` (TypeScript code, no `resolveJsonModule` required)
-- ⚛️ Works perfectly with `React.lazy()` and dynamic imports
-- 📘 Full TypeScript `.d.ts` definitions included
-- 🧩 Custom route file name (default: `page.ts`)
-- 🪶 Zero runtime dependencies
-- 🎯 Clean, formatted output with readable keys
+- 🔍 **Automatic folder scanning** - Recursively scans your pages/screens directory
+- 📄 **Generated TypeScript routes** - Fully typed `routes.ts` file with `as const` assertions
+- ⚛️ **Framework agnostic** - Works with React.lazy, Vue, Solid, or any framework with dynamic imports
+- 🪶 **Zero runtime dependencies** - Only used at build/dev time
+- 🔄 **File watcher support** - Auto-regenerate routes when files change (powered by Chokidar)
+- 🎨 **Biome formatting** - Output files are automatically formatted with Biome
+- 🧩 **Vite plugin** - Seamless integration with Vite dev server
+- 🚫 **Smart file filtering** - Ignores `index` files, `_` prefixed files (private routes), and output files
+- 📘 **Full TypeScript support** - Complete `.d.ts` definitions included
 
 ---
 
@@ -21,16 +22,24 @@ Automatically scans folders and outputs a clean, structured `routes.ts` tree rea
 
 ```bash
 npm install ts-file-router
-# or
-yarn add ts-file-router
+```
+
+**Optional dependencies:**
+
+```bash
+# For file watcher support
+npm install chokidar
 
+# Vite is automatically supported as a peer dependency
 ```
 
 ---
 
-## 🎯 Usage
+## 🚀 Quick Start
+
+### 1. Basic Usage (One-time generation)
 
-Create a script to generate your routes. Example:
+Create a script to generate your routes:
 
 ```js
 // scripts/generate-routes.mjs
@@ -38,68 +47,239 @@ import { generateRoutes } from 'ts-file-router';
 
 generateRoutes({
   baseFolder: 'src/screens',
-  outputFile: 'src/screens/routes.ts',
+  outputFile: 'routes.ts',
 });
 ```
 
-## 🎯 Usage With Vite
+Run it:
+
+```bash
+node scripts/generate-routes.mjs
+```
 
-Create a script to generate your routes. Example:
+### 2. With File Watcher (Auto-regenerate on changes)
 
 ```js
-// scripts/vite.config.ts
+// scripts/generate-routes.mjs
+import { generateRoutes } from 'ts-file-router';
+
+generateRoutes({
+  baseFolder: 'src/screens',
+  outputFile: 'routes.ts',
+  options: {
+    watcher: {
+      watch: true,
+      debounce: 500, // Wait 500ms after changes before regenerating
+    },
+    exitCodeOnResolution: false, // Don't exit process after generation
+  },
+});
+```
+
+This will keep running and regenerate routes whenever you add, remove, or modify files in the `src/screens` folder.
+
+### 3. With Vite Plugin
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
 import { generateRoutesPlugin } from 'ts-file-router';
 
-// https://vite.dev/config/
 export default defineConfig({
   plugins: [
     generateRoutesPlugin({
       baseFolder: 'src/screens',
-      outputFile: 'screens.ts',
+      outputFile: 'src/screens/routes.ts',
+      // Optional: customize watcher behavior
+      options: {
+        watcher: { watch: true, debounce: 500 },
+        exitCodeOnResolution: false,
+      },
     }),
   ],
 });
 ```
 
-## 🎯 Usage With Watcher (Chokidar Peer Dependencie)
+The plugin automatically runs during Vite's dev server (`vite dev`) and regenerates routes on file changes.
+
+---
 
-Create a script to generate your routes. Example:
+## 📂 How It Works
 
-```js
-// scripts/generate-routes.mjs
-import { generateRoutes } from 'ts-file-router';
+Given this folder structure:
 
-generateRoutes({
-  baseFolder: 'src/screens',
-  outputFile: 'screens.ts',
-  options: {
-    watcher: { watch: true, debounce: 500 },
-    exitCodeOnResolution: false,
+```
+src/screens/                  # Home page
+├── about/
+│   └── page.tsx               # About page
+├── users/
+│   ├── page.tsx               # Users list
+│   ├── profile/
+│   │   └── page.tsx          # User profile
+│   └── _private/
+│       └── page.tsx          # Ignored (starts with _)
+└── index.tsx                  # Ignored (index file)
+```
+
+Generates:
+
+```ts
+// GENERATED WITH TS-FILE-ROUTER DO NOT EDIT
+export const routes = {
+  about: {
+    path: '/about',
+    import: () => import('./about/page'),
   },
-});
+  users: {
+    page: {
+      path: '/users',
+      import: () => import('./users/page'),
+    },
+    profile: {
+      path: '/users/profile',
+      import: () => import('./users/profile/page'),
+    },
+  },
+} as const;
 ```
 
-## What this does
+---
 
-- baseFolder: Root directory where your screens/pages live
+## 🔧 Configuration Options
 
-- routeFileName: File that represents a route (e.g. page.tsx)
+### `generateRoutes()` Parameters
 
-- outputFile: Generated routes file (fully typed)
+| Parameter    | Type                     | Required | Description                        |
+| ------------ | ------------------------ | -------- | ---------------------------------- |
+| `baseFolder` | `string`                 | ✅ Yes   | Root directory to scan for routes  |
+| `outputFile` | `string`                 | ✅ Yes   | Path for the generated routes file |
+| `options`    | `TGenerateRoutesOptions` | ❌ No    | Additional configuration           |
 
-Run the script with:
+### Options Object
 
-node scripts/generate-routes.mjs
+```ts
+interface TGenerateRoutesOptions {
+  watcher?: {
+    watch: boolean; // Enable file watching
+    debounce?: number; // Debounce delay in ms (default: 500)
+  };
+  exitCodeOnResolution?: boolean; // Exit process after generation (default: true)
+}
+```
 
-or setup generateRoutesPlugin in vite.config.ts
+### `exitCodeOnResolution`
 
-## Output based on your folder
+- **`true`** (default for CLI): Process exits with code `0` on success or `1` on error
+- **`false`** (default for Vite/plugin): Process keeps running (required for watchers)
 
-```ts
-export const routes = {
-  page: {
-    path: '/',
-    import: import('./page'),
-  },
-} as const;
+---
+
+## 🎯 Usage Examples
+
+### With React Router And React Lazy Using
+
+```tsx
+import { routes } from './screens/routes';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import React from 'react';
+
+const About = lazy(() =>
+  routes.about.import().then((r) => ({ default: res.About })),
+);
+
+const Profile = lazy(() =>
+  routes.users.profile.import().then((r) => ({ default: res.Profile })),
+);
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path={routes.about.path} element={<About />} />
+        <Route path={routes.users.profile.path} element={<Profile />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+---
+
+## 🚫 File Filtering Rules
+
+The following files/folders are **automatically ignored**:
+
+- **`index.*`** files - Index files are skipped
+- **`_` prefixed** files/folders - Files starting with underscore are treated as private
+- **Output file** - The generated routes file is ignored to prevent infinite loops
+
+This allows you to have helper files, components, or private routes alongside your page files without polluting the routes tree.
+
+---
+
+## 📦 Output File Structure
+
+The generated file is a TypeScript module with:
+
+- ✅ `export const routes` - Named export with all routes
+- ✅ `as const` assertion - Full type inference for route paths and imports
+
+## 🛠 Advanced Usage
+
+### Custom Route File Names
+
+By default, any file (except ignored ones) becomes a route. You can control this by:
+
+1. Using a consistent naming convention (e.g., all pages named `page.tsx`)
+2. Using `_` prefix for non-route files: `_components.tsx`, `_utils.ts`
+
+### Watcher Events
+
+When using the watcher, routes regenerate on:
+
+- `add` - New file added
+- `addDir` - New directory added
+- `change` - File modified
+- `unlink` - File deleted
+- `unlinkDir` - Directory deleted
+
+If the output file is deleted, it's automatically regenerated.
+
+### Graceful Shutdown
+
+The watcher listens for:
+
+- `SIGINT` (Ctrl+C) - Graceful cleanup
+- `SIGTERM` - Container/process termination
+
+Both trigger proper watcher cleanup before exit.
+
+---
+
+## 📝 Tips
+
+1. **Add to `package.json`**:
+
+```json
+{
+  "scripts": {
+    "generate:routes": "node scripts/generate-routes.mjs",
+    "dev": "npm run generate:routes && vite",
+    "dev:watch": "node scripts/generate-routes.mjs --watch"
+  }
+}
 ```
+
+2. **Use relative paths in output**: The `outputFile` path is relative to `baseFolder`.
+
+---
+
+## 🤝 Contributing
+
+Found a bug or have a feature request? Open an issue or submit a PR!
+
+---
+
+## 📄 License
+
+ISC © MatheusF10

package/dist/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKrE,eAAO,MAAM,cAAc,GAAI,sCAI5B,qBAAqB,SA6IvB,CAAC"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKrE,eAAO,MAAM,cAAc,GAAI,sCAI5B,qBAAqB,SAmKvB,CAAC"}

package/dist/generator.js

@@ -8,38 +8,45 @@ export const generateRoutes = ({ baseFolder, outputFile, options = { exitCodeOnR
     const output = path.resolve(basePath, outputFile);
     const mapRoutes = async (dir) => {
         const routes = {};
-        const directory = await fs.readdir(dir);
-        for (const file of directory) {
-            if (!directory.length || directory.length === 0) {
+        try {
+            const directory = await fs.readdir(dir);
+            if (!directory || !directory.length || directory.length === 0) {
                 throw new Error(`Invalid pages structure: The folder "${dir}" must contain at least one valid file.`);
             }
-            // ignore index files, underscore marked, or route file generated
-            if (FileHelper.getIgnoredFiles(file, outputFile)) {
-                continue;
-            }
-            const fullPath = path.join(dir, file);
-            // Get directory info to control file or folder
-            const dirInfo = await fs.stat(fullPath);
-            // Path to browser sync if necessary
-            const relativePath = '/' + path.relative(basePath, dir);
-            const importPath = './' + path.relative(basePath, fullPath);
-            // Remove extension from file to naming the route
-            const key = path.basename(file, path.extname(file));
-            if (dirInfo.isDirectory()) {
-                // Dev friendly when enter in this conditional file is a directory(folder)
-                const directory = file;
-                // Recursively for sub directories
-                routes[directory] = await mapRoutes(fullPath);
-                continue;
+            for (const file of directory) {
+                // ignore index files, underscore marked, or route file generated
+                if (FileHelper.getIgnoredFiles(file, outputFile)) {
+                    continue;
+                }
+                const fullPath = path.join(dir, file);
+                // Get directory info to control file or folder
+                const dirInfo = await fs.stat(fullPath);
+                // Path to browser sync if necessary
+                const relativePath = '/' + path.relative(basePath, dir);
+                const importPath = './' + path.relative(basePath, fullPath);
+                // Remove extension from file to naming the route
+                const key = path.basename(file, path.extname(file));
+                if (dirInfo.isDirectory()) {
+                    // Dev friendly when enter in this conditional file is a directory(folder)
+                    const directory = file;
+                    // Recursively for sub directories
+                    routes[directory] = await mapRoutes(fullPath);
+                    continue;
+                }
+                // Mount the route object with path like "/folder" and import
+                // import will be like "import((./baseFolder/file or ./baseFolder/folders).extension)"
+                routes[key] = {
+                    // Normalize path
+                    path: FileHelper.cleanPaths(relativePath),
+                    // Normalize import path to esm pattern
+                    import: FileHelper.cleanPaths(importPath),
+                };
             }
-            // Mount the route object with path like "/folder" and import
-            // import will be like "import((./baseFolder/file or ./baseFolder/folders).extension)"
-            routes[key] = {
-                // Normalize path
-                path: FileHelper.cleanPaths(relativePath),
-                // Normalize import path to esm pattern
-                import: FileHelper.cleanPaths(importPath),
-            };
+        }
+        catch (err) {
+            console.error(`Error mapping routes ${dir}:`, err);
+            // Stop the process immediatelly
+            process.exit(1);
         }
         return routes;
     };
@@ -80,6 +87,7 @@ export const generateRoutes = ({ baseFolder, outputFile, options = { exitCodeOnR
                 createRoutes();
             }, debounce);
         };
+        runFromWatcher();
         watcher.on('all', (ev, file) => {
             const ignoredOuput = FileHelper.getIgnoredOutputFile(file, outputFile);
             // If output file as deleted regenerate it
@@ -102,7 +110,16 @@ export const generateRoutes = ({ baseFolder, outputFile, options = { exitCodeOnR
                 runFromWatcher();
             }
         });
-        return () => watcher.close();
+        const cleanup = async () => {
+            console.log('🛑 Stopping watcher...');
+            await watcher.close();
+            // Code 0 to finish the process as success
+            process.exit(0);
+        };
+        // If CRTL + C was pressed
+        process.on('SIGINT', cleanup);
+        // If Script or container treatment
+        process.on('SIGTERM', cleanup);
     };
     if (!!options.watcher) {
         watcher(options.watcher);

package/dist/helpers/serializeHelper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializeHelper.d.ts","sourceRoot":"","sources":["../../src/helpers/serializeHelper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAqJtD,eAAO,MAAM,eAAe;kCAnHA,OAAO,KAAG,KAAK,IAAI,UAAU;2CAoGd,WAAW,cAAc,MAAM;kDAlBxB,MAAM,QAAQ,MAAM;CAqC5D,CAAC"}
+{"version":3,"file":"serializeHelper.d.ts","sourceRoot":"","sources":["../../src/helpers/serializeHelper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA0JtD,eAAO,MAAM,eAAe;kCAxHA,OAAO,KAAG,KAAK,IAAI,UAAU;2CAyGd,WAAW,cAAc,MAAM;kDAhBxB,MAAM,QAAQ,MAAM;CAmC5D,CAAC"}

package/dist/helpers/serializeHelper.js

@@ -20,8 +20,8 @@ const getBiomeSingleton = async () => {
         });
     }
     return {
+        biome: biomeInstance.biome,
         projectKey: biomeInstance.project.projectKey,
-        formatContent: biomeInstance.biome.formatContent,
     };
 };
 // Type guard
@@ -36,7 +36,12 @@ const createRouteObject = (obj) => {
         if (isRouteLeaf(value)) {
             return ts.factory.createPropertyAssignment(ts.factory.createIdentifier(key), ts.factory.createObjectLiteralExpression([
                 ts.factory.createPropertyAssignment('path', ts.factory.createStringLiteral(value.path)),
-                ts.factory.createPropertyAssignment('import', ts.factory.createCallExpression(ts.factory.createIdentifier('import'), undefined, [ts.factory.createStringLiteral(value.import)])),
+                ts.factory.createPropertyAssignment('import', ts.factory.createArrowFunction(undefined, // modifiers
+                undefined, // type parameters
+                [], // parameters
+                undefined, // return type
+                ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), // =>
+                ts.factory.createCallExpression(ts.factory.createIdentifier('import'), undefined, [ts.factory.createStringLiteral(value.import)]))),
             ], true));
         }
         // Recursive object
@@ -56,10 +61,8 @@ const createRoutesFile = (obj) => {
     return ts.factory.createSourceFile([exportStatement], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
 };
 const formatAndWriteOutputFile = async (filePath, code) => {
-    const biomeInstance = await getBiomeSingleton();
-    const formatted = biomeInstance.formatContent(biomeInstance.projectKey, code, {
-        filePath: path.basename(filePath),
-    });
+    const biomeSingleton = await getBiomeSingleton();
+    const formatted = biomeSingleton.biome.formatContent(biomeSingleton.projectKey, code, { filePath: path.basename(filePath) });
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, formatted.content, 'utf8');
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-file-router",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "router based on project files using typescript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,7 @@
     "vite": ">=3.0.0"
   },
   "dependencies": {
-    "@biomejs/js-api": "^4.0.0",
-    "@biomejs/wasm-nodejs": "^2.3.11"
+    "@biomejs/js-api": "4.0.0",
+    "@biomejs/wasm-nodejs": "2.3.11"
   }
 }