Updated component prompts

stack-auth · mantrakp04 · Apr 14, 2026 · Mar 20, 2026 · Mar 27, 2026 · Mar 27, 2026
commit 9f9000ee230c70ba7b0ccb724b7a91f76b2f4e9b
diff --git a/apps/backend/src/app/api/latest/internal/component-versions/route.ts b/apps/backend/src/app/api/latest/internal/component-versions/route.ts
@@ -1,6 +1,6 @@
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { yupNumber, yupObject, yupRecord, yupString } from "@stackframe/stack-shared/dist/schema-fields";
-import { getLatestPageVersions } from "@stackframe/stack-shared/dist/interface/page-component-versions";
+import { getLatestPageVersions } from "@stackframe/stack-shared/dist/interface/handler-urls";
 
 export const GET = createSmartRouteHandler({
   metadata: {

diff --git a/claude/CLAUDE-KNOWLEDGE.md b/claude/CLAUDE-KNOWLEDGE.md
@@ -161,3 +161,21 @@ A: Use `signed_up_at` (OIDC-style naming) in access tokens and encode it as Unix
 
 Q: Where should new globally searchable Cmd+K destinations be added in the dashboard?
 A: Add project-level shortcuts to `PROJECT_SHORTCUTS` in `apps/dashboard/src/components/cmdk-commands.tsx` (optionally gated with `requiredApps`), and for app subpages rely on the flattened `appFrontend.navigationItems` command generation in the same file so pages are directly searchable without nested preview navigation.
+
+Q: How should handler URL/shared interface renames be rolled out when template/backend import `@stackframe/stack-shared/dist/*`?
+A: Add the new source entrypoint in `packages/stack-shared/src/interface` and update imports to the new `dist` path, but validate with package typechecks after the stack-shared dist artifacts are refreshed (for example via existing dev watchers), because consumers resolve through `dist/*` entrypoints rather than `src/*`.
+
+Q: How are custom page prompts organized in `page-component-versions.ts` now?
+A: `signIn` and `signUp` share a single `createAuthPagePrompt(type)` helper, and all remaining pages (`signOut`, `emailVerification`, `passwordReset`, `forgotPassword`, `oauthCallback`, `magicLinkCallback`, `accountSettings`, `teamInvitation`, `mfa`, `error`, `onboarding`) now use `createCustomPagePrompt(...)` with concise logical `structure` plus a React `reactExample`.
+
+Q: What makes custom page prompt examples actionable for coding agents?
+A: Avoid abstract placeholders for core flows (for example undefined section components or form primitives). In `page-component-versions.ts`, examples are most useful when they inline the section/form components and state transitions they rely on, while keeping `structure` focused on logical behavior rather than visual layout.
+
+Q: How detailed should the Account Settings custom-page prompt be?
+A: The `accountSettings` prompt should enumerate each top-level page and each subsection's exact responsibilities and API calls (emails, password, passkey, OTP, MFA, notifications, sessions, API keys, payments, settings, team pages, team creation). The example should inline section components and actions rather than referencing undefined placeholders.
+
+Q: What should we do if dashboard typecheck fails with syntax errors in `apps/dashboard/.next/dev/types/routes.d.ts`?
+A: Regenerate Next route types with `pnpm --filter @stackframe/dashboard exec next typegen` (and if needed, delete the corrupted `apps/dashboard/.next/dev/types/routes.d.ts` first). This fixes transient generated-file corruption without changing source code.
+
+Q: What is the current `getCustomPagePrompts` API shape?
+A: `getCustomPagePrompts` now takes no arguments and returns all prompts directly; call it as `getCustomPagePrompts()` instead of passing an SDK package name.
diff --git a/packages/stack-shared/src/interface/handler-urls.ts b/packages/stack-shared/src/interface/handler-urls.ts
@@ -0,0 +1,48 @@
+/**
+ * @deprecated Plain string URLs are deprecated. Use `{ type: "custom", url: "...", version: 0 }` instead.
+ */
+type DeprecatedStringUrl = string;
+
+export type HandlerPageUrls = Record<
+  | "handler"
+  | "signIn"
+  | "signUp"
+  | "signOut"
+  | "emailVerification"
+  | "passwordReset"
+  | "forgotPassword"
+  | "oauthCallback"
+  | "magicLinkCallback"
+  | "accountSettings"
+  | "teamInvitation"
+  | "mfa"
+  | "error"
+  | "onboarding",
+  DeprecatedStringUrl | { type: "custom", url: string, version: number } | { type: "hosted" | "handler-component" }
+>;
+
+export type HandlerRedirectUrls = Record<
+  | "afterSignIn"
+  | "afterSignUp"
+  | "afterSignOut"
+  | "home",
+  string
+>;
+
+export type HandlerUrls = HandlerPageUrls & HandlerRedirectUrls;
+export type HandlerUrlTarget = HandlerUrls[keyof HandlerUrls];
+export type DefaultHandlerUrlTarget = string | { type: "hosted" | "handler-component" };
+export type HandlerUrlOptions = Partial<HandlerUrls> & { default?: DefaultHandlerUrlTarget };
+export type ResolvedHandlerUrls = {
+  [K in keyof HandlerUrls]: string;
+};
+
+export {
+  getCustomPagePrompts,
+  getLatestPageVersions,
+  type CustomPagePrompt,
+  type PageComponentKey,
+  type PageVersionEntry,
+  type PageVersions
+} from "./page-component-versions";
+