vue-router-auth
Skill2 starsChanged 35 days agoMITView on GitHub
Use when adding routes, navigation guards, login/logout flows, permission-driven menus or button-level permissions to a Vue 3 + Vue Router 4 app. Enforces a single dynamic-route registration after login, correct 401/403 handling, keep-alive tab caching that actually works, and guards that never loop.
In this repository13 other files it gives its agents.
- api-layer-axiosSkill
- element-plus-adminSkill
- nuxt3-appSkill
- pinia-stateSkill
- uni-app-cross-platformSkill
- vue2-to-vue3-migrationSkill
- vue3-compositionSkill
- vue-code-reviewSkill
- vue-forms-validationSkill
- vue-i18n-setupSkill
- vue-performanceSkill
- vue-testing-vitestSkill
- wechat-miniprogramSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
Distinguish three failures and handle each in one place: No token: guard redirects to login.
- Distinctive: line 154
Remove the element rather than hiding it: a hidden button still submits with Enter and still shows in the DOM for a curious user.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Vue Router, auth and permissions
This skill covers the routing layer of an admin app: static vs permission
routes, the login guard, redirect-back, menu generation, button permissions
and <keep-alive> tabs. "Good" means a user with a stale token lands on login
exactly once, a user with no permission sees 403 instead of a blank page, and
closing a tab frees its memory. Skip it for marketing sites with no login.
Non-negotiables
- Two route tables, never one.
constantRoutes(login, 403, 404, redirect, dashboard) are registered at router creation.asyncRoutesare filtered by the user's permissions and added withrouter.addRoute()after login. Mixing them means the login page itself gets permission-checked. - Register dynamic routes exactly once per session, tracked by a store
flag (
routesAdded). The guard checks the flag, not the token, to decide whether to add routes. Re-adding on every navigation duplicates routes and the warnings hide real bugs. - After
addRoute, re-navigate by returning{ ...to, replace: true }from the guard. The current navigation was resolved before the routes existed, so it would resolve to 404.replace: truekeeps the back button sane. - The 404 catch-all (
/:pathMatch(.*)*) is added last, after dynamic routes. Register it inasyncRoutestail or add it manually after the loop. A catch-all inconstantRoutesswallows every dynamic path. - Whitelist by path, not by name, and keep the list under 5 entries
(
/login,/403,/404,/redirect/*). A long whitelist is a sign that the auth check belongs in the API layer instead. - Distinguish three failures and handle each in one place. No token:
guard redirects to login. Token expired (401): the axios interceptor
clears the store and redirects once. Forbidden (403): the guard or
interceptor sends to
/403, never to login, because re-logging in does not help. - Redirect back after login via
?redirect=carryingto.fullPath. Validate it is a relative path starting with/before using it to avoid open redirects. - Guards do no async work on every navigation. Fetching user info happens
once (when
routesAddedis false). A guard that awaits an API call on each route change adds 100–300 ms to every click. - Menus come from the route table's
meta, not from a second hand-written list. Two sources of truth drift within a month. <keep-alive include>matches the component'sname, so the.vuefile must declaredefineOptions({ name: 'UserList' })equal to the route name. Without it the include list silently does nothing.- Logout resets the store, removes dynamic routes and hard-redirects.
router.removeRoute()per added name, or simplylocation.href = '/login'to drop all in-memory state. The second is acceptable; a half-reset is not.
Workflow
- Inspect the existing guard (
router/permission.tsorrouter/guard.ts): find the token source, the whitelist, whereaddRouteis called and what flag prevents re-adding. Do not add a second guard; extend the one that exists. - Classify the new page: public (constant), authenticated-only
(asyncRoutes without
meta.perms), or permission-gated (meta.perms: ['user:list']). Pick the matching route array. - Define the route with
name, lazycomponent: () => import(...),meta: { title, icon, perms, keepAlive, hidden }. The name is the tab key and the keep-alive key, so it is unique and matchesdefineOptions. - Add button permissions with
v-permission="'user:delete'"on the element orhasPerm('user:delete')inside logic. Both read the same permission set from the store. - Verify three journeys by hand or Playwright: fresh visit to a deep
link while logged out → login → lands on the deep link; expired token on
an API call → login once, no loop; user without the permission →
/403, and the menu item is absent.
Patterns
The guard skeleton
router.beforeEach(async (to) => {
const auth = useAuthStore()
if (WHITE_LIST.includes(to.path)) return true
if (!auth.token) return { path: '/login', query: { redirect: to.fullPath } }
if (auth.routesAdded) return true
try {
await auth.fetchUserInfo() // once per session
buildRoutes(auth.perms).forEach((r) => router.addRoute(r))
router.addRoute(NOT_FOUND) // catch-all last
auth.routesAdded = true
return { ...to, replace: true } // re-run against new table
} catch {
auth.reset()
return { path: '/login', query: { redirect: to.fullPath } }
}
})Filtering routes by permission
function buildRoutes(perms: Set<string>, routes = asyncRoutes): RouteRecordRaw[] {
return routes.flatMap((r) => {
const need = r.meta?.perms as string[] | undefined
if (need && !need.some((p) => perms.has(p))) return []
const children = r.children ? buildRoutes(perms, r.children) : undefined
if (r.children && children!.length === 0) return [] // drop empty parents
return [{ ...r, children }]
})
}Dropping parents with no visible children keeps the menu from showing empty groups.
Safe redirect-back
// wrong: open redirect
router.push(route.query.redirect as string)
// right
const target = String(route.query.redirect ?? '/')
router.push(target.startsWith('/') && !target.startsWith('//') ? target : '/')401 handling in the API layer, not the guard
let redirecting = false
api.interceptors.response.use(undefined, (err) => {
if (err.response?.status === 401 && !redirecting) {
redirecting = true
useAuthStore().reset()
router.replace({ path: '/login', query: { redirect: router.currentRoute.value.fullPath } })
.finally(() => (redirecting = false))
}
return Promise.reject(err)
})Five parallel requests failing with 401 must produce one redirect, hence the flag.
Button permission directive
app.directive('permission', {
mounted(el, { value }) {
const perms = useAuthStore().perms
const need = Array.isArray(value) ? value : [value]
if (!need.some((p) => perms.has(p))) el.parentNode?.removeChild(el)
},
})Remove the element rather than hiding it: a hidden button still submits with Enter and still shows in the DOM for a curious user. The server still checks.
Keep-alive tabs
<router-view v-slot="{ Component }">
<keep-alive :include="tabsStore.cachedNames">
<component :is="Component" :key="route.fullPath" />
</keep-alive>
</router-view>cachedNames holds component names, which equal route names by convention.
Closing a tab removes its name from the list; keep-alive then unmounts it
on the next navigation.
Pitfalls
| Symptom | Cause | Fix |
Infinite redirect between /login and / | Guard redirects to login, login page is not whitelisted, or routesAdded never set | Whitelist /login; set the flag before returning |
| Deep link shows 404 after login | Navigation resolved before addRoute | Return { ...to, replace: true } after adding |
| Every page is 404 for everyone | Catch-all registered in constantRoutes | Add catch-all after dynamic routes |
| Duplicate route name warnings | addRoute runs on each navigation | Gate on routesAdded |
| Menu shows a group with no pages | Parent kept after children filtered out | Drop parents whose children are empty |
| Tab closed but component still polling | Component name differs from route name | defineOptions({ name }) equal to route name |
| Page keeps old data when reopened | Cached by keep-alive, no refresh | Reload in onActivated, not onMounted |
| Login page bounces back to itself | ?redirect=/login carried over | Never store /login as redirect target |
| User logs out, next user sees old menu | Store reset without removing routes | removeRoute each added name, or hard redirect |
| 401 triggers five login redirects | No single-flight flag in interceptor | Add redirecting flag |
| Guard adds 200 ms to every click | await fetchUserInfo() on each navigation | Fetch once, gated by flag |
| Scroll position wrong on back | No scrollBehavior | scrollBehavior: (to, from, saved) => saved ?? { top: 0 } |
Before you finish
- New route is in the correct table (constant vs async) with a unique
name. componentis lazy (() => import()),metahas title and, if gated,perms.- If
meta.keepAlive, the component declaresdefineOptions({ name })equal to the route name. - Catch-all is still the last route after your change.
- Gated buttons use
v-permission/hasPerm, and the server also enforces the permission. - Walked the three journeys: logged-out deep link, expired token, missing permission.
- No new async work in
beforeEachthat runs on every navigation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

