Skip to content

Melvynx/saveit.now / .agents/skills/ns-intercepted-route-using-tanstack-start

ns-intercepted-route-using-tanstack-start

Verified

Implement masked modal routes in NowStack Mobile web-app. Use for TanStack Start route masks, shareable detail URLs, back-to-close, and refresh-to-page behavior.

Intercepted Route Using TanStack Start

Current route shape:

  • Public: /, /privacy, /cgv, /support
  • User app: /app
  • Admin: /admin (redirects to /admin/users), /admin/users, /admin/users/$userId

The examples below use a hypothetical /admin/items list/detail flow to illustrate the pattern.

  1. User starts on /admin/items.
  2. User clicks a row.
  3. Browser URL becomes /admin/items/$itemId.
  4. UI keeps the /admin/items list visible and opens a modal/sheet with the detail.
  5. Back or close returns to /admin/items.
  6. Refresh or direct visit on /admin/items/$itemId renders the full detail page.

<core_pattern> Navigate to the source route internally, store modal state in source route search, and mask the visible URL as the destination route.

<Link
  to="/admin/items"
  search={{ itemId: item._id }}
  mask={{
    to: "/admin/items/$itemId",
    params: { itemId: item._id },
    unmaskOnReload: true,
  }}
  resetScroll={false}
>
  View
</Link>

The source route owns modal state:

type ItemsSearch = {
  itemId?: string;
};

export const Route = createFileRoute("/admin/items")({
  validateSearch: (search: Record<string, unknown>): ItemsSearch => ({
    itemId:
      typeof search.itemId === "string" && search.itemId.length > 0
        ? search.itemId
        : undefined,
  }),
  component: AdminItemsPage,
});

The destination route remains a real route:

export const Route = createFileRoute("/admin/items/$itemId")({
  component: AdminItemDetailPage,
});

</core_pattern>

const router = useRouter();
const location = useLocation();

const closeModal = () => {
  if (location.maskedLocation) {
    router.history.back();
    return;
  }

  void router.navigate({
    to: "/admin/items",
    search: {},
    replace: true,
  });
};

If the modal has an "Open full page" action, navigate directly and do not call the close handler first:

void router.navigate({
  to: "/admin/items/$itemId",
  params: { itemId },
  replace: true,
});
cd web-app && npm run typecheck
cd web-app && npm run build

Then verify manually or with browser automation:

  1. Open source route.
  2. Click detail link.
  3. Confirm browser URL is the detail URL.
  4. Confirm modal/sheet is visible over source context.
  5. Use Back or close and confirm source route returns.
  6. Open detail URL directly or refresh and confirm full detail page renders.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall