docs: add route config desc & update en docs #4857
Conversation
ArthurDarkstone
requested review from
anncwb,
vince292007 and
a team
as code owners
|
WalkthroughThe pull request introduces several modifications to the routing configurations across multiple Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
|
maybe help with #4854 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (15)
apps/web-antd/src/router/routes/index.ts (2)
Line range hint
8-9: Translate Chinese comment to English for consistency.Consider translating the comment "有需要可以自行打开注释，并创建文件夹" to English to maintain documentation consistency.
-// 有需要可以自行打开注释，并创建文件夹 +// You can uncomment and create folders if needed
24-25: Improve comment formatting for better readability.The multi-line comment could be formatted more clearly.
-/** 路由列表，由基本路由、外部路由和404兜底路由组成 - * 无需走权限验证（会一直显示在菜单中） */ +/** + * Route list composed of core routes, external routes, and 404 fallback route. + * No permission validation required (always displayed in the menu). + */apps/web-ele/src/router/routes/index.ts (1)
Line range hint
8-8: Consider translating the Chinese comment for consistency.For better maintainability and consistency with English documentation, consider translating the comment "有需要可以自行打开注释，并创建文件夹" to English.
-// 有需要可以自行打开注释，并创建文件夹 +// Uncomment and create folders if neededapps/web-naive/src/router/routes/index.ts (2)
24-25: Improve comment readability and structure.The comment's meaning is correct but could be more readable. Consider restructuring it as follows:
-/** 路由列表，由基本路由、外部路由和404兜底路由组成 - * 无需走权限验证（会一直显示在菜单中） */ +/** 路由列表：包含基本路由、外部路由和404兜底路由。 + * 特点： + * - 无需权限验证 + * - 始终显示在菜单中 + */
Line range hint
1-37: Well-structured route organization.The route management approach demonstrates good architectural decisions:
- Clear separation of concerns between different route types
- Modular organization using dynamic imports
- Proper handling of fallback routes
- Clear permission boundaries between verified and unverified routes
Consider documenting these routing patterns in the project's architecture documentation to establish them as team conventions.
playground/src/router/routes/index.ts (2)
24-25: Enhance security implications in route documentation.While the comment clarifies that these routes bypass permission validation, it would be beneficial to explicitly document:
- Security considerations for routes without permission checks
- Guidelines for determining which routes should skip validation
Consider updating the comment to:
-/** 路由列表，由基本路由、外部路由和404兜底路由组成 - * 无需走权限验证（会一直显示在菜单中） */ +/** 路由列表，由基本路由、外部路由和404兜底路由组成 + * 无需走权限验证（会一直显示在菜单中） + * 注意: 仅将必要的公共路由添加到此列表中，因为这些路由将绕过权限检查 */
35-37: Consider enhancing type safety for exported routes.The documentation clearly explains the purpose of
accessRoutes. However, consider improving type safety by:
- Creating a custom type for routes that require permission validation
- Adding runtime validation for route configurations
Example implementation:
/** Type for routes that require permission validation */ type AccessRoute = RouteRecordRaw & { meta: { requiresAuth: true; permissions?: string[]; }; }; /** 有权限校验的路由列表，包含动态路由和静态路由 */ const accessRoutes: AccessRoute[] = [...dynamicRoutes, ...staticRoutes];docs/src/guide/essentials/route.md (2)
15-23: Well-structured core routes documentation with good architectural guidance!The documentation effectively explains core routes and their configuration. The tip about keeping business routes separate from core routes is particularly valuable for maintaining a clean architecture.
This separation of concerns between core routes and business routes helps maintain a cleaner codebase and makes the application more maintainable and scalable.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~17-~17: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...s)。 ### 核心路由 核心路由是框架内置的路由，包含了根路由、登录路由、404路由等，核心路由的配置在应用下src/router/routes/core...(wa5)
27-33: Documentation is clear, consider adding a configuration example.The explanation of static routes and permission control is accurate and helpful. While the content is good, consider adding a simple configuration example to illustrate the
authorityfield usage in themetaattribute.Consider adding a brief example like:
{ path: '/admin', meta: { authority: ['admin', 'super-user'], // Example permission control } }docs/src/en/guide/essentials/route.md (6)
9-9: Enhance the machine translation notice.The current notice is vague. Consider specifying which parts are machine-translated and whether they have been reviewed for accuracy.
-This page is translated by machine translation and may not be very accurate. +Parts of this documentation have been machine translated. While we strive for accuracy, some sections may require further review. Please report any unclear or incorrect translations.
17-19: Improve the structure of route types explanation.The explanation of route types could be more structured for better readability.
-Routes are divided into core routes, static routes, and dynamic routes. Core routes are built-in routes of the framework, including root routes, login routes, 404 routes, etc.; static routes are routes that are determined when the project starts; dynamic routes are generally generated dynamically based on the user's permissions after the user logs in. +Routes are divided into three types: +1. Core Routes: Built-in framework routes (root routes, login routes, 404 routes, etc.) +2. Static Routes: Routes determined at project startup +3. Dynamic Routes: Routes generated based on user permissions after login
Line range hint
64-107: Enhance code examples with explanatory comments.The example would be more educational with inline comments explaining key configurations.
const routes: RouteRecordRaw[] = [ { component: BasicLayout, meta: { + // Display a dot badge with destructive (red) color badgeType: 'dot', badgeVariants: 'destructive', + // Use custom logo as menu icon icon: VBEN_LOGO_URL, + // Control menu item order (higher numbers appear later) order: 9999, + // Translated menu title title: $t('page.vben.title'), }, name: 'VbenProject', path: '/vben-admin', + // Default child route when accessing /vben-admin redirect: '/vben-admin/about', children: [ // ... rest of the code
291-291: Enhance verification section with debugging tips.The verification section could be more helpful with common troubleshooting steps.
At this point, the page has been added. Visit `http://localhost:5555/home/index` to see the corresponding page. +If the page doesn't appear as expected: +1. Check the browser console for any route-related errors +2. Verify that the route is registered correctly in the Vue Router debug panel +3. Ensure all required meta properties are properly configured +4. Check that the component is being loaded (look for network requests)
586-591: Enhance query property documentation with examples.The query property documentation would be more helpful with practical examples.
### query - Type: `Recordable` - Default: `{}` Used to configure the menu parameters of the page, which will be passed to the page in the menu. +Example usage: +```ts +{ + meta: { + query: { + tab: 'overview', + filter: 'active' + } + } +} +``` + +This will append `?tab=overview&filter=active` to the route URL when accessed from the menu.
Line range hint
595-607: Expand the Route Refresh section with use cases and considerations.The refresh functionality documentation could be more comprehensive.
The route refresh method is as follows: +Common use cases for route refresh: +- Reloading data after external changes +- Resetting component state +- Forcing re-evaluation of route guards + +Note: Refreshing will re-render the entire route component tree and may clear component state. + ```vue <script setup lang="ts"> import { useRefresh } from '@vben/hooks'; const { refresh } = useRefresh(); // Refresh the current route refresh(); </script>🧰 Tools
🪛 LanguageTool
[style] ~449-~449: You have already used ‘Generally’ in other nearby sentences. Consider replacing or removing it to add variety to your writing.
Context: ...e, which will be displayed in the menu. Generally used with an icon library, if it is an ...(REP_SENT_START_ADVERBLY)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (6)
apps/web-antd/src/router/routes/index.ts(2 hunks)apps/web-ele/src/router/routes/index.ts(2 hunks)apps/web-naive/src/router/routes/index.ts(2 hunks)docs/src/en/guide/essentials/route.md(11 hunks)docs/src/guide/essentials/route.md(1 hunks)playground/src/router/routes/index.ts(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/src/en/guide/essentials/route.md
[style] ~449-~449: You have already used ‘Generally’ in other nearby sentences. Consider replacing or removing it to add variety to your writing.
Context: ...e, which will be displayed in the menu. Generally used with an icon library, if it is an ...
(REP_SENT_START_ADVERBLY)
docs/src/guide/essentials/route.md
[uncategorized] ~11-~11: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...核心路由、静态路由和动态路由，核心路由是框架内置的路由，包含了根路由、登录路由、404路由等；静态路由是在项目启动时就已经确定的路由；动态路由一般是在用户登录后，根据用...
(wa5)
[uncategorized] ~17-~17: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...s)。 ### 核心路由 核心路由是框架内置的路由，包含了根路由、登录路由、404路由等，核心路由的配置在应用下 src/router/routes/core ...
(wa5)
🔇 Additional comments (7)
apps/web-antd/src/router/routes/index.ts (1)
35-37: LGTM! Clear documentation and correct implementation.
The comment clearly explains the purpose of accessRoutes, and the implementation correctly combines dynamic and static routes for permission validation.
apps/web-ele/src/router/routes/index.ts (3)
24-25: LGTM! Clear documentation of route composition and permissions.
The comment effectively explains that these routes don't require permission verification and will always be displayed in the menu.
35-37: LGTM! Well-structured route exports with clear documentation.
The combination of dynamic and static routes into accessRoutes is logical, and the comment clearly explains its purpose. The exports are well-organized and properly documented.
Line range hint 8-13: Verify the intentional removal of dynamic route imports.
The initialization of staticRoutes and externalRoutes has been changed from dynamic imports to empty arrays. While the commented code suggests this is optional ("有需要可以自行打开注释"), this change could affect the application's routing behavior.
Let's check if this pattern is consistent across other router configurations:
Also applies to: 22-23
✅ Verification successful
Empty route arrays and commented imports are consistent across all web apps
The search results confirm this is an intentional pattern consistently implemented across all three web applications (web-ele, web-naive, and web-antd). Each app:
- Initializes
staticRoutesandexternalRoutesas empty arrays - Contains the same commented-out dynamic imports with identical comments
- Maintains the same structure for route configuration
This consistency across the codebase validates that the changes are intentional and part of a standardized approach, not a potential issue.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check for similar route initialization patterns in other router files
# Expected: Similar empty array initialization or commented imports
# Search for route initialization patterns
rg -A 5 "const (static|external)Routes.*=.*\[\]" "apps/"
# Search for commented route file imports
rg -A 5 "const.*RouteFiles.*=.*import\.meta\.glob.*eager.*" "apps/"
Length of output: 3397
apps/web-naive/src/router/routes/index.ts (1)
35-37: Verify the intention of empty staticRoutes array.
The code shows commented imports for static routes but initializes staticRoutes as an empty array. Please confirm if this is intentional.
Let's check if there are any static route files in the project:
✅ Verification successful
Based on the search results, I can now generate the final response since I have sufficient context to verify the intention of the empty staticRoutes array.
Empty staticRoutes array is intentional - part of the framework's design
The empty staticRoutes array is intentional as evidenced by:
- All web applications (web-naive, web-antd, web-ele) consistently use this pattern
- Documentation (docs/src/en/guide/essentials/route.md) explains that static routes are optional and meant for routes determined at project start
- The commented import
staticRouteFilesis left as a template for developers to uncomment when they need to add static routes
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check for the existence of static route files
# Expected: No static route files if the empty array is intentional
# Look for any static route files
fd -t f . -p "*/router/routes/static/**/*.ts"
# Check for any TODOs or comments about static routes
rg -i "static.*route" -g "!*.{lock,json}" -A 3
Length of output: 9261
playground/src/router/routes/index.ts (1)
22-23: Verify the intentional initialization of empty route arrays.
The staticRoutes and externalRoutes are initialized as empty arrays, while the previous implementation using mergeRouteModules is commented out. This could potentially impact the routing functionality if these routes are expected to be populated.
✅ Verification successful
The search results reveal that this is a consistent pattern across multiple applications in the codebase (web-naive, web-ele, web-antd, and playground). All of them have identical changes where:
- The route loading code is commented out
- Empty arrays are used instead
- These empty arrays are still used in route composition
Let me verify if there are any dynamic routes being loaded to understand if this is part of a broader simplification:
Empty route arrays are intentional - dynamic routes are the primary source
The verification reveals this is an intentional architectural decision across all applications (playground, web-naive, web-ele, web-antd):
- Dynamic routes are actively loaded using
mergeRouteModules(dynamicRouteFiles) - Static and external routes are consistently initialized as empty arrays
- Route files exist under
modules/directories (dashboard, demos, vben) which are loaded as dynamic routes
The empty arrays for staticRoutes and externalRoutes represent a deliberate simplification of the routing system to use dynamic routes as the primary source, while maintaining the flexibility to add static/external routes in the future.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check if there are any static or external route files that should be loaded
# Expected: No matching files if empty arrays are intentional
echo "Checking for static route files..."
fd -e ts . "playground/src/router/static"
echo "Checking for external route files..."
fd -e ts . "playground/src/router/external"
# Check if these routes are used elsewhere
echo "Checking route usage..."
rg "staticRoutes|externalRoutes" --type ts
Length of output: 2865
Script:
#!/bin/bash
# Check for dynamic route loading implementation
echo "Checking dynamic routes implementation..."
rg "dynamicRoutes.*=" -A 5 --type ts
# Check if there are any route files in the codebase
echo "Checking for route files..."
fd -e ts -e vue . | rg -i "route"
Length of output: 4440
docs/src/guide/essentials/route.md (1)
11-14: Documentation structure and content look good!
The explanation of route types and permission control is clear and comprehensive. The distinction between core, static, and dynamic routes is well-defined, and the permission control mechanism is accurately described.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~11-~11: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...核心路由、静态路由和动态路由，核心路由是框架内置的路由，包含了根路由、登录路由、404路由等；静态路由是在项目启动时就已经确定的路由；动态路由一般是在用户登录后，根据用...
(wa5)
Description
Type of change
Please delete options that are not relevant.
pnpm-lock.yamlunless you introduce a new test example.Checklist
pnpm run docs:devcommand.pnpm test.feat:,fix:,perf:,docs:, orchore:.Summary by CodeRabbit
New Features
Documentation
Chores