@onoxm/vite-plugin-auto-router 0.2.1 → 0.3.1

package/README.md

@@ -0,0 +1,436 @@
+# @onoxm/vite-plugin-auto-router
+
+A Vite plugin for automatically generating React or Vue route files.
+
+English | [中文](./README.zh-CN.md)
+
+## ✨ Features
+
+- Auto-generate route configuration, no manual maintenance needed
+- Supports both React and Vue frameworks
+- Convention-based routing, automatically mapped by directory structure
+- Supports dynamic route `[id]` syntax
+- `home` page path automatically converted to `/` (configurable)
+- `root` page as root route container (configurable)
+- Configurable lazy loading and hot module replacement
+- Supports page-level configuration files
+- TypeScript type safety
+
+## 🚀 Installation
+
+```bash
+npm install -D @onoxm/vite-plugin-auto-router
+```
+
+## 📖 Usage Guide
+
+### React Project
+
+#### Install Dependencies
+
+```bash
+npm install react-router
+```
+
+#### Configure Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import autoRouter from '@onoxm/vite-plugin-auto-router'
+
+export default defineConfig({
+  plugins: [react(), autoRouter()]
+})
+```
+
+#### Directory Structure
+
+```
+src/
+├── pages/
+│   ├── index.tsx
+│   ├── root.tsx
+│   ├── 404.tsx
+│   └── user/
+│       ├── index.tsx
+│       ├── index.config.ts
+│       ├── [id].tsx
+│       └── [id].config.ts
+```
+
+#### Special Pages
+
+- **`home` page**: Path automatically converted to `/`, used as home route
+- **`root` page**: Used as root route container, wrapping all other routes
+- **`404` or `notfound` page**: Path automatically converted to `/*`, used as 404 route
+
+#### Page Configuration
+
+Inherits from [React Router RouteObject](https://reactrouter.com/start/data/route-object), with the following modifications:
+
+- **Removed**: `path`, `Component`, `element`, `children`
+- **Added**: `type?: 'single' | 'wrap'`
+
+##### type: 'single'
+
+When `type` is set to `single`, the page component will be generated as an independent route:
+
+```typescript
+// src/pages/user/index.config.ts
+import { defineConfig } from '../../router/autoRouter'
+
+export default defineConfig({
+  type: 'single'
+})
+```
+
+Generated route structure:
+
+```typescript
+// src/router/autoRouter.tsx
+import type { RouteObject } from 'react-router'
+import Pages404 from './../pages/404.tsx'
+import Pages from './../pages/index.tsx'
+import PagesRoot from './../pages/root.tsx'
+import PagesUser from './../pages/user/index.tsx'
+import PagesUserId from './../pages/user/[id]/index.tsx'
+
+type PageConfig = Partial<
+  Omit<RouteObject, 'path' | 'Component' | 'element' | 'children'> & {
+    type?: 'single' | 'wrap'
+  }
+>
+
+export const defineConfig = (config: PageConfig) => config
+
+export const routes: RouteObject[] = [
+  {
+    path: '/',
+    element: <PagesRoot />,
+    children: [
+      {
+        path: '/',
+        element: <Pages />
+      },
+      {
+        path: '/user',
+        children: [
+          {
+            path: '',
+            index: true,
+            element: <PagesUser />
+          },
+          {
+            path: ':id',
+            children: [
+              {
+                path: '',
+                index: true,
+                action: async () => {},
+                loader: async ({ params }) => await { params },
+                element: <PagesUserId />
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    path: '/*',
+    element: <Pages404 />
+  }
+]
+```
+
+##### type: 'wrap'
+
+When `type` is set to `wrap`, the page component will act as a parent route container wrapping its child routes:
+
+```typescript
+// src/pages/user/index.config.ts
+import { defineConfig } from '../../router/autoRouter'
+
+export default defineConfig({
+  type: 'wrap'
+})
+```
+
+Generated route structure:
+
+```typescript
+// src/router/autoRouter.tsx
+import type { RouteObject } from 'react-router'
+import Pages404 from './../pages/404.tsx'
+import Pages from './../pages/index.tsx'
+import PagesRoot from './../pages/root.tsx'
+import PagesUser from './../pages/user/index.tsx'
+import PagesUserId from './../pages/user/[id]/index.tsx'
+
+type PageConfig = Partial<
+  Omit<RouteObject, 'path' | 'Component' | 'element' | 'children'> & {
+    type?: 'single' | 'wrap'
+  }
+>
+
+export const defineConfig = (config: PageConfig) => config
+
+export const routes: RouteObject[] = [
+  {
+    path: '/',
+    element: <PagesRoot />,
+    children: [
+      {
+        path: '/',
+        element: <Pages />
+      },
+      {
+        path: '/user',
+        element: <PagesUser />,
+        children: [
+          {
+            path: ':id',
+            children: [
+              {
+                path: '',
+                index: true,
+                action: async () => {},
+                loader: async ({ params }) => await { params },
+                element: <PagesUserId />
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    path: '/*',
+    element: <Pages404 />
+  }
+]
+```
+
+### Vue Project
+
+#### Install Dependencies
+
+```bash
+npm install vue-router
+```
+
+#### Configure Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import autoRouter from '@onoxm/vite-plugin-auto-router'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    autoRouter({
+      framework: 'vue',
+      pagesDir: './src/views'
+    })
+  ]
+})
+```
+
+#### Directory Structure
+
+```
+src/
+├── views/
+│   ├── 404.vue
+│   ├── home/
+│   │   ├── index.vue
+│   │   └── index.config.ts
+│   └── user/
+│       ├── index.vue
+│       ├── index.config.ts
+│       ├── [id].vue
+│       └── [id].config.ts
+```
+
+#### Special Pages
+
+- **`home` page**: Path automatically converted to `/`, used as home route
+- **`root` page**: Used as root route container, wrapping all other routes
+- **`404` or `notfound` page**: Path automatically converted to `/:pathMatch(.*)*`, used as 404 route
+
+#### Page Configuration
+
+Inherits from [Vue Router RouteRecordRaw](https://router.vuejs.org/api/#routerecordraw), with the following modifications:
+
+- **Removed**: `path`, `component`, `children`
+- **Added**: `type?: 'single' | 'wrap'`
+
+##### type: 'single'
+
+When `type` is set to `single`, the page component will be generated as an independent route:
+
+```typescript
+// src/views/user/index.config.ts
+import { defineConfig } from '../../router/autoRouter'
+
+export default defineConfig({
+  type: 'single'
+})
+```
+
+Generated route structure:
+
+```typescript
+// src/router/autoRouter.ts
+import type { RouteRecordRaw } from 'vue-router'
+import Views404 from './../views/404.vue'
+import ViewsHome from './../views/home/index.vue'
+import ViewsUser from './../views/user/index.vue'
+import ViewsUserId from './../views/user/[id]/index.vue'
+
+type PageConfig = Partial<
+  Omit<RouteRecordRaw, 'path' | 'component' | 'children'> & {
+    type?: 'single' | 'wrap'
+  }
+>
+
+export const defineConfig = (config: PageConfig) => config
+
+export const routes: RouteRecordRaw[] = [
+  {
+    path: '/',
+    children: [
+      {
+        path: '',
+        name: 'home',
+        component: ViewsHome
+      }
+    ]
+  },
+  {
+    path: '/user',
+    children: [
+      {
+        path: '',
+        component: ViewsUser
+      },
+      {
+        path: ':id',
+        children: [
+          {
+            path: '',
+            component: ViewsUserId
+          }
+        ]
+      }
+    ]
+  },
+  {
+    path: '/:pathMatch(.*)*',
+    children: [
+      {
+        path: '',
+        component: Views404
+      }
+    ]
+  }
+]
+```
+
+##### type: 'wrap'
+
+When `type` is set to `wrap`, the page component will act as a parent route container wrapping its child routes:
+
+```typescript
+// src/views/user/index.config.ts
+import { defineConfig } from '../../router/autoRouter'
+
+export default defineConfig({
+  type: 'wrap'
+})
+```
+
+Generated route structure:
+
+```typescript
+// src/router/autoRouter.ts
+import type { RouteRecordRaw } from 'vue-router'
+import Views404 from './../views/404.vue'
+import ViewsHome from './../views/home/index.vue'
+import ViewsUser from './../views/user/index.vue'
+import ViewsUserId from './../views/user/[id]/index.vue'
+
+type PageConfig = Partial<
+  Omit<RouteRecordRaw, 'path' | 'component' | 'children'> & {
+    type?: 'single' | 'wrap'
+  }
+>
+
+export const defineConfig = (config: PageConfig) => config
+
+export const routes: RouteRecordRaw[] = [
+  {
+    path: '/',
+    children: [
+      {
+        path: '',
+        name: 'home',
+        component: ViewsHome
+      }
+    ]
+  },
+  {
+    path: '/user',
+    component: ViewsUser,
+    children: [
+      {
+        path: ':id',
+        children: [
+          {
+            path: '',
+            component: ViewsUserId
+          }
+        ]
+      }
+    ]
+  },
+  {
+    path: '/:pathMatch(.*)*',
+    children: [
+      {
+        path: '',
+        component: Views404
+      }
+    ]
+  }
+]
+```
+
+## ⚙️ Configuration Options
+
+### Plugin Configuration
+
+| Option       | Type               | Default         | Description                         |
+| ------------ | ------------------ | --------------- | ----------------------------------- |
+| `framework`  | `'react' \| 'vue'` | `'react'`       | Framework type                      |
+| `pagesDir`   | `string`           | `'./src/pages'` | Pages directory                     |
+| `routesFile` | `string`           | `undefined`     | Generated route file path           |
+| `keepHome`   | `boolean`          | `false`         | Whether to keep home page path      |
+| `keepRoot`   | `boolean`          | `false`         | Whether to keep root page path      |
+| `lazy`       | `boolean`          | `true`          | Whether to enable lazy loading      |
+| `hmr`        | `boolean`          | `false`         | Whether to enable hot module update |
+
+### Page Configuration
+
+| Option | Type                 | Default    | Description                 |
+| ------ | -------------------- | ---------- | --------------------------- |
+| `type` | `'single' \| 'wrap'` | `'single'` | Route type                  |
+| `*`    | `any`                | `any`      | Inherits from router config |
+
+## 📄 License
+
+MIT