菜单
Use when a project wants to update the router_builder package to a newer version and the migration path is unclear - "upgrade router_builder", "move to the latest router_builder", dependency bumps from 1.x or 2.x, or deciding whether an upgrade is breaking before touching code.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | upgrade-router-builder |
| description | Use when a project wants to update the router_builder package to a newer version and the migration path is unclear - "upgrade router_builder", "move to the latest router_builder", dependency bumps from 1.x or 2.x, or deciding whether an upgrade is breaking before touching code. |
Determine the installed version, pick the path, delegate the one breaking hop to its dedicated skill. Never guess the version from imports alone.
grep -A2 "router_builder" pubspec.lock (the lockfile is truth;
pubspec constraints can be stale).dart pub outdated shows it).Routes/RoutesHelper/routes.g.dart and policy: RoutePolicy(...) mean
3.x; MyRoutes/RouteInfoHelper/route_info_helper.dart or flat params
(isGlobalOnly:, isIdSlug:) mean 1.x/2.x.| From -> To | Path |
|---|---|
| 3.x -> newer 3.x | Bump constraint, flutter pub get, dart run build_runner build, dart analyze, run tests. 3.0.1 only relaxed the analyzer constraint; no code changes. |
| 2.x -> 3.x | BREAKING. Use the migrate-v2-to-v3 skill (codemod + manual policy folds + regenerate + host audit). |
| 1.x -> 3.x | Two hops: first 1.x -> 2.0.4 (below), then migrate-v2-to-v3. |
| 1.x -> 2.x only | Deps-only hop (below). |
| 0.x | Never published to pub.dev; a 0.x source tree predates the unified deep-link system. Treat as legacy: consult the package MIGRATION_GUIDE.md appendix (v0 -> v1 deep-link registry migration), then continue up the chain. |
2.0.0-2.0.4 updated analyzer/build_runner-era dependencies and merged the additive 1.2.0 policy system; it removed nothing. Mechanics:
router_builder: ^2.0.4, flutter pub get. Resolve any
analyzer/build_runner solve conflicts (2.0.3/2.0.4 exist precisely to relax
analyzer/dart_style/dart_helper_utils ranges).dart run build_runner build) and dart analyze.RouteInfo.replaceAll ->
shouldReplaceAll. The analyzer flags any survivor.RoutePolicy here; that is the v3
migration's job. Keep hops separate and verifiable.Use when adding, renaming, or removing a screen, route, tab, popup, redirect, or deep link in a Flutter app that uses the router_builder package - the one with @RT annotations, RouteInfo, RouteArgs, RoutePolicy, and a generated routes.g.dart with Routes/RoutesHelper classes.
Use when a deep link in a router_builder Flutter app opens the wrong screen or nothing at all, RoutesHelper.resolveDeepLink or DeepLinkMatcher.match returns null, custom-scheme links (myapp://...) behave differently from https links, allowedHosts seem ignored, deepLinkMap keys do not resolve, or the build fails with deep-link key conflicts.
Use when router_builder code generation misbehaves - routes.g.dart missing, stale, or not updating, build_runner failing with RouterBuilderError (deep-link key conflicts, @RTConfig errors, branch enum mismatch), @RT routes not discovered, dependency solve failures around analyzer/build/source_gen/dart_style when adding or upgrading router_builder, or customizing builder options (output path, class names, fail_on_conflict).
Use when a router_builder route behaves unexpectedly at runtime - auth gates firing on public screens or not firing on private ones, routes stacking duplicates or refusing to open twice, dialogs/sheets not treated as popups, navigation landing inside the wrong navigator or replacing the whole stack, redirect routes looping, nav bar visibility wrong, or RoutesHelper category lists (authorizedRoutes, globalRoutes, popupRoutes) not matching expectations.
Use when executing a confirmed router_builder 2.x to 3.x upgrade, or when code shows v2 tells - flat RouteInfo/RouteArgs params like isGlobalOnly/isIdSlug/mustBeAuthorized as constructor args, imports of package:router_builder/models/..., MyRoutes/RouteInfoHelper, a generated route_info_helper.dart, or RouterBuilderConfig.setDefaults with named parameters. For a version bump where the path is still unclear, start with upgrade-router-builder.
Use when proactively auditing a Flutter app's router_builder route definitions while nothing is failing yet - before a release, after adding many routes, when asked to "check our routes/deep links/auth gating", or when hunting for misconfigured RoutePolicy, latent deep-link key conflicts, or auth gaps across @RT declarations.