Awesome

ElegantRouter

English | 中文

Introduction

ElegantRouter is a tool for creating routes based on the file system, which can automatically generate route definitions, route file imports and route-related type definitions. Just create the route file according to the agreed rules, without adding any additional configuration in the route file.

Differences and similarities

The main difference between ElegantRouter and other file system-based routing tools is that:

Other tools have complex configuration rules, and the route data is a black box, which is difficult to customize.
ElegantRouter follows the api-first principle and automates the process of configuring routes.

Taking configuring Vue routes as an example, the traditional way of creating page routes requires the following steps:

Import the layout component
Import the page component
Define the route in the route configuration file

Although these steps are not complicated, in actual development, they are repetitive and need to be done manually. In addition, the maintenance of route names and paths is very troublesome, there is no clear agreement on the route definition of the layout and page components, resulting in a messy route definition. And using ElegantRouter, you only need to create the route file according to the agreed rules, you can automatically generate the route in the specified route file.

ElegantRouter's route configuration process

You only need to create a route file according to the agreed rules to generate the route in the specified route file.

Installation

Install the Vue version (other frameworks to come...)

pnpm install @elegant-router/vue

Use

Introduce the plugin in Vite

import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import ElegantVueRouter from "@elegant-router/vue/vite";

export default defineConfig({
  plugins: [
    vue(),
    ElegantVueRouter({
      alias: {
        "@": "src",
      },
      layouts: {
        base: "src/layouts/base-layout/index.vue",
        blank: "src/layouts/blank-layout/index.vue",
      },
    }),
  ],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

Integration in Vue Router

src/router/routes/index.ts

import type { ElegantRoute, CustomRoute } from "@elegant-router/types";
import { generatedRoutes } from "../elegant/routes";
import { layouts, views } from "../elegant/imports";
import { transformElegantRoutesToVueRoutes } from "../elegant/transform";

const customRoutes: CustomRoute[] = [
  {
    name: "root",
    path: "/",
    redirect: {
      name: "403",
    },
  },
  {
    name: "not-found",
    path: "/:pathMatch(.*)*",
    component: "layout.base$view.404",
  },
];

const elegantRoutes: ElegantRoute[] = [...customRoutes, ...generatedRoutes];

export const routes = transformElegantRoutesToVueRoutes(
  elegantRoutes,
  layouts,
  views
);

src/router/index.ts

import { createRouter, createWebHistory } from "vue-router";
import { routes } from "./routes";

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
});

export default router;

Starting the project

After starting the project, the plugin will automatically generate the src/router/elegant directory, and the files in this directory are the automatically generated route import, route definition and route transformation files.

Configuration

Route file creation

You can configure pagePatterns to specify the rules for creating route files. The rules for creating route files are regular expressions, and if the path of a route file matches the regular expression, the route file will be created.

Default: all files named index.vue、[id].vue、[module].vue, etc. below the folder.

pagePatterns: ["**‍/index.vue", "**‍/[[]*[]].vue"];

One-level route (single-level route)

Folder structure

views
├── about
│   └── index.vue

Generated routes

{
  name: 'about',
  path: '/about',
  component: 'layout.base$view.about',
  meta: {
    title: 'about'
  }
},

it is a single level route, to add layout, the component props combines the layout and view component, split by the dollar sign "$"

Transformed Vue routes

{
  path: '/about',
  component: BaseLayout,
  children: [
    {
      name: 'about',
      path: '',
      component: () => import('@/views/about/index.vue'),
      meta: {
        title: 'about'
      }
    }
  ]
},

Secondary route

Folder structure

views
├── list
│   ├── home
│   │   └── index.vue
│   ├── detail
│   │   └── index.vue

Please don't have the following index.vue on the same level as the folder, this is not part of the agreed upon rules

Error example

views
├── list
│   ├── index.vue
│   ├── detail
│   │   └── index.vue

Generated routes

{
  name: 'list',
  path: '/list',
  component: 'layout.base',
  meta: {
    title: 'list'
  },
  children: [
    {
      name: 'list_home',
      path: '/list/home',
      component: 'view.list_home',
      meta: {
        title: 'list_home'
      }
    },
    {
      name: 'list_detail',
      path: '/list/detail',
      component: 'view.list_detail',
      meta: {
        title: 'list_detail'
      }
    },
  ]
}

There are two layers of route data for secondary routes, the first layer of route is the layout component and the second layer of route is the page component

Transformed Vue routes

{
  name: 'list',
  path: '/list',
  component: BaseLayout,
  redirect: {
    name: 'list_home'
  },
  meta: {
    title: 'list'
  },
  children: [
    {
      name: 'list_home',
      path: '/list/home',
      component: () => import('@/views/list/home/index.vue'),
      meta: {
        title: 'list_home'
      }
    },
    {
      name: 'list_detail',
      path: '/list/detail',
      component: () => import('@/views/list/detail/index.vue'),
      meta: {
        title: 'list_detail'
      }
    }
  ]
},

the first layer of route data contains the redirection configuration, which by default redirects to the first sub-route

Multi-level route (level 3 route and above)

Folder structure

The folder hierarchy is deep

views
├── multi-menu
│   ├── first
│   │   ├── child
│   │   │   └── index.vue
│   ├── second
│   │   ├── child
│   │   │   ├── home
│   │   │   │   └── index.vue

Two-tier folder hierarchy (recommended)

views
├── multi-menu
│   ├── first_child
│   │   └── index.vue
│   ├── second_child_home
│   │   └── index.vue

The route hierarchy is split by the underscore symbol "_", which prevents the folder hierarchy from being too deep.

Generated routes

{
  name: 'multi-menu',
  path: '/multi-menu',
  component: 'layout.base',
  meta: {
    title: 'multi-menu'
  },
  children: [
    {
      name: 'multi-menu_first',
      path: '/multi-menu/first',
      meta: {
        title: 'multi-menu_first'
      },
      children: [
        {
          name: 'multi-menu_first_child',
          path: '/multi-menu/first/child',
          component: 'view.multi-menu_first_child',
          meta: {
            title: 'multi-menu_first_child'
          }
        }
      ]
    },
    {
      name: 'multi-menu_second',
      path: '/multi-menu/second',
      meta: {
        title: 'multi-menu_second'
      },
      children: [
        {
          name: 'multi-menu_second_child',
          path: '/multi-menu/second/child',
          meta: {
            title: 'multi-menu_second_child'
          },
          children: [
            {
              name: 'multi-menu_second_child_home',
              path: '/multi-menu/second/child/home',
              component: 'view.multi-menu_second_child_home',
              meta: {
                title: 'multi-menu_second_child_home'
              }
            }
          ]
        }
      ]
    }
  ]
}

if the route level is greater than 2, the generated route data is a recursive structure

Transformed Vue routes

{
  name: 'multi-menu',
  path: '/multi-menu',
  component: BaseLayout,
  redirect: {
    name: 'multi-menu_first'
  },
  meta: {
    title: 'multi-menu'
  },
  children: [
    {
      name: 'multi-menu_first',
      path: '/multi-menu/first',
      redirect: {
        name: 'multi-menu_first_child'
      },
      meta: {
        title: 'multi-menu_first'
      }
    },
    {
      name: 'multi-menu_first_child',
      path: '/multi-menu/first/child',
      component: () => import('@/views/multi-menu/first_child/index.vue'),
      meta: {
        title: 'multi-menu_first_child'
      }
    },
    {
      name: 'multi-menu_second',
      path: '/multi-menu/second',
      redirect: {
        name: 'multi-menu_second_child'
      },
      meta: {
        title: 'multi-menu_second'
      },
    },
    {
      name: 'multi-menu_second_child',
      path: '/multi-menu/second/child',
      redirect: {
        name: 'multi-menu_second_child_home'
      },
      meta: {
        title: 'multi-menu_second_child'
      },
    },
    {
      name: 'multi-menu_second_child_home',
      path: '/multi-menu/second/child/home',
      component: () => import('@/views/multi-menu/second_child_home/index.vue'),
      meta: {
        title: 'multi-menu_second_child_home'
      }
    }
  ]
},

the transformed Vue routes only has two levels, the first level is the layout component, and the second level is the redirect routes or the page routes

Ignore folder aggregation routes

Folder names that begin with an underscore "_" will be ignored

Folder structure

views
├── _error
│   ├── 403
│   │   └── index.vue
│   ├── 404
│   │   └── index.vue
│   ├── 500
│   │   └── index.vue

Generated routes

{
  name: '403',
  path: '/403',
  component: 'layout.base$view.403',
  meta: {
    title: '403'
  }
},
{
  name: '404',
  path: '/404',
  component: 'layout.base$view.404',
  meta: {
    title: '404'
  }
},
{
  name: '500',
  path: '/500',
  component: 'layout.base$view.500',
  meta: {
    title: '500'
  }
},

Parameter Route

Folder structure

views
├── user
│   └── [id].vue

Generated routes

{
  name: 'user',
  path: '/user/:id',
  component: 'layout.base$view.user',
  props: true,
  meta: {
    title: 'user'
  }
}

Advanced parameter route

import type { RouteKey } from "@elegant-router/types";

ElegantVueRouter({
  routePathTransformer(routeName, routePath) {
    const routeKey = routeName as RouteKey;

    if (routeKey === "user") {
      return "/user/:id(\\d+)";
    }

    return routePath;
  },
});

Custom Route

the custom route is only used to generate the route declaration, and the route file is not generated, you should create the route file manually.

Config custom routes

ElegantVueRouter({
  customRoutes: {
    map: {
      root: "/",
      notFound: "/:pathMatch(.*)*",
    },
    names: ["two-level_route"],
  },
});

Generated CustomRouteKey

type RouteMap = {
  root: "/";
  notFound: "/:pathMatch(.*)*";
  "two-level": "/two-level";
  "two-level_route": "/two-level/route";
};

type CustomRouteKey = "root" | "notFound" | "two-level" | "two-level_route";

Custom routes's component

it can use existing page components as the route component

import type { CustomRoute } from "@elegant-router/types";

const customRoutes: CustomRoute[] = [
  {
    name: "root",
    path: "/",
    redirect: {
      name: "403",
    },
  },
  {
    name: "not-found",
    path: "/:pathMatch(.*)*",
    component: "layout.base$view.404",
  },
  {
    name: "two-level",
    path: "/two-level",
    component: "layout.base",
    children: [
      {
        name: "two-level_route",
        path: "/two-level/route",
        component: "view.about",
      },
    ],
  },
];

Plugin Option

ElegantRouterOption:

property	instruction	type	default value
cmd	the root directory of the project	`string`	`process.cwd()`
pageDir	the relative path to the root directory of the pages	`string`	`"src/views"`
alias	alias, it can be used for the page and layout file import path	`Record<string, string>`	`{ "@": "src" }`
pagePatterns	the patterns to match the page files (the match syntax follow micromatch)	`string[]`	`["‍/index.vue", "‍/[[]*[]].vue"]`
pageExcludePatterns	the patterns to exclude the page files (The default exclusion folder `components` is used as the routing page file.)	`string[]`	`["‍/components/"]`
routeNameTransformer	transform the route name (The default is the name of the folder connected by an underscore)	`(routeName: string) => string`	`routeName => routeName`
routePathTransformer	transform the route path	`(transformedName: string, path: string) => string`	`(_transformedName, path) => path`

ElegantVueRouterOption:

extends ElegantRouterOption

property	instruction	type	default value
dtsDir	the declaration file directory of the generated routes	`string`	`"src/typings/elegant-router.d.ts"`
importsDir	the directory of the imports of routes	`string`	`"src/router/elegant/imports.ts"`
lazyImport	whether the route is lazy import	`(routeName: string) => boolean`	`_name => true`
constDir	the directory of the route const	`string`	`"src/router/elegant/routes.ts"`
customRoutes	define custom routes, which's route only generate the route declaration	`{ map: Record<string, string>; names: string[] }`	`{ map: { root: "/", notFound: "/:pathMatch(\)\" }, names: []}`
layouts	the name and file path of the route layouts	`Record<string, string>`	`{ base: "src/layouts/base-layout/index.vue", blank: "src/layouts/blank-layout/index.vue" }`
defaultLayout	the default layout name used in generated route const ( takes the first layout of `layouts` by default.)	`string`	`"base"`
layoutLazyImport	whether the route is lazy import	`(layoutName: string) => boolean`	`_name => false`
transformDir	the directory of the routes transform function (Converts the route definitions of the generated conventions into routes for the vue-router.)	`string`	`"src/router/elegant/transform.ts"`
onRouteMetaGen	the route meta generator	`(routeName: string) => Record<string, string>`	`routeName => ({ title: routeName })`

Caveat

Folder naming: can only contain letters, numbers, dash, underscore, and no other special characters

The underscore is a cut identifier for the routing hierarchy, and the short horizontal line is used to connect multiple words in a one-level route
The reason the generated route data is two-level is to fit in with vue-router's page caching functionality, and because KeepAlive is only related to the name of the Vue file and not the route name, the plugin automatically injects the name attribute into the Vue file, which has the value of the route name
```
defineOptions({
  name: "about",
});
```
Currently only the script setup mode is supported, which injects the above defineOptions function.