registerRoutes static method

void registerRoutes()

Register the /preview catalog page and its /preview/:component deep link.

Router-lock timing (load-bearing)

MagicRouter locks its route table the first time routerConfig is accessed (MagicRouter.routerConfig builds the GoRouter and sets _isBuilt, after which addRoute throws StateError). The consumer MUST therefore call registerRoutes inside a provider boot() — which runs during the Magic bootstrap lifecycle, BEFORE MaterialApp reads MagicRouter.instance.routerConfig — otherwise the routes register too late and /preview silently never appears.

Release boundary

The body is gated by kReleaseMode (early return) and kPreviewEnabled (a const bool.fromEnvironment). Both fold to a dead branch in release, so the route, the MagicPreviewCatalog, and every registered PreviewEntry are proven unreachable and tree-shaken from the bundle.

Implementation

static void registerRoutes() {
  // 1. Hard release boundary: nothing below this line survives a release
  //    build (const-folded dead by the optimizer).
  if (kReleaseMode) return;
  if (!kPreviewEnabled) return;

  // 2. Snapshot the entries inside this function body (never a top-level
  //    const list — sdk#33920) so the catalog widget receives them by value.
  final List<PreviewEntry> entries = _entries;

  // 3. Two plain pages render the catalog DIRECTLY (no persistent shell): the
  //    index shows the first entry; `/preview/:component` selects an entry by
  //    its slug. The `:component` builder RECEIVES the slug and rebuilds on
  //    every navigation, so deep-linking (`/preview/<slug>`) and sidebar
  //    selection both resolve the right entry. A persistent ShellRoute would
  //    NOT rebuild when only the child route swapped, leaving the catalog
  //    stuck on the first entry.
  MagicRoute.page(
    '/preview',
    () => MagicPreviewCatalog(
      entries: entries,
      onSelect: (entry) => MagicRoute.to('/preview/${entry.slug}'),
    ),
  ).name('magic-preview.index');

  MagicRoute.page(
    '/preview/:component',
    (String component) => MagicPreviewCatalog(
      entries: entries,
      activeSlug: component,
      onSelect: (entry) => MagicRoute.to('/preview/${entry.slug}'),
    ),
  ).name('magic-preview.component');
}