From 1018c6f4f134103cbdf6edae59e550da9ad723ed Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Thu, 5 Mar 2026 14:37:16 -0600 Subject: [PATCH 1/3] fix: improve TanStack Start skill to reduce first-attempt build failures Three changes to address common agent self-correction patterns: 1. Use createStart(() => ({ ... })) as the default start.ts pattern. The generated routeTree.gen.ts imports createStart types, so a plain object export fails type checking. createStart takes a function returning the options, not the options directly. 2. Add Finalize section with mandatory pre-completion steps: regenerate route tree, ensure vite-env.d.ts exists, verify the build. 3. Instruct agents to read existing start.ts before modifying, matching the project's export style instead of rewriting from scratch. --- skills/workos-authkit-tanstack-start/SKILL.md | 58 ++++++++++++++----- 1 file changed, 45 insertions(+), 13 deletions(-) diff --git a/skills/workos-authkit-tanstack-start/SKILL.md b/skills/workos-authkit-tanstack-start/SKILL.md index 36356de7..02d3d542 100644 --- a/skills/workos-authkit-tanstack-start/SKILL.md +++ b/skills/workos-authkit-tanstack-start/SKILL.md @@ -87,33 +87,32 @@ Default redirect URI: `http://localhost:3000/api/auth/callback` **authkitMiddleware MUST be configured or auth will fail silently.** **WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.** +### If `start.ts` already exists -Create or update `src/start.ts` (or `app/start.ts` for legacy): +Read the existing file first. Add `authkitMiddleware` to the existing `requestMiddleware` array (or create the array if missing). Preserve the existing export style. Do not rewrite the file from scratch. -```typescript -import { authkitMiddleware } from '@workos/authkit-tanstack-react-start'; +### If `start.ts` does not exist -export default { - requestMiddleware: [authkitMiddleware()], -}; -``` - -Alternative pattern with createStart: +Create `src/start.ts` (or `app/start.ts` for legacy) using `createStart`: ```typescript import { createStart } from '@tanstack/react-start'; import { authkitMiddleware } from '@workos/authkit-tanstack-react-start'; -export default createStart({ +export const startInstance = createStart(() => ({ requestMiddleware: [authkitMiddleware()], -}); +})); ``` +**Two things matter here:** +1. **Named export `startInstance`** — the build plugin generates `import type { startInstance }` from this file. A `default` export will cause a build error. +2. **`createStart` takes a function** returning the options object, not the options directly. `createStart({ ... })` will fail. + ### Verification Checklist - [ ] `authkitMiddleware` imported from `@workos/authkit-tanstack-react-start` -- [ ] Middleware in `requestMiddleware` array -- [ ] File exports the config (default export or named `startInstance`) +- [ ] Middleware in `requestMiddleware` array (not `middleware`) +- [ ] Named export: `export const startInstance = createStart(...)` (not `export default`) Verify: `grep -r "authkitMiddleware" src/ app/ 2>/dev/null` @@ -210,6 +209,39 @@ function Profile() { **Note:** Server-side `getAuth()` is preferred for most use cases. +## Finalize (REQUIRED before declaring success) + +After creating/editing all files, run these steps in order. Skipping them is the most common cause of build failures. + +### 1. Regenerate the route tree + +Adding new route files (callback, signout, etc.) makes the existing `routeTree.gen.ts` stale. The build will fail with type errors about missing routes until it is regenerated. + +```bash +pnpm build 2>/dev/null || npx tsr generate +``` + +The build itself triggers route tree regeneration. If it fails for other reasons, use `tsr generate` directly. + +### 2. Ensure Vite type declarations exist + +TanStack Start projects import CSS with `import styles from './styles.css?url'`. Without Vite's type declarations, TypeScript will error on these imports. Check if `src/vite-env.d.ts` (or `app/vite-env.d.ts`) exists — if not, create it now (before attempting the build): + +```typescript +/// +``` + +### 3. Verify the build + +```bash +pnpm build +``` + +Do not skip this step. If the build fails, fix the errors before finishing. Common causes: +- Stale route tree → re-run step 1 +- Missing Vite types → re-run step 2 +- Wrong import paths → check package name is `@workos/authkit-tanstack-react-start` + ## Error Recovery ### "AuthKit middleware is not configured" From debebaa48fea086d212d7cee361852cb44b9a243 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Thu, 5 Mar 2026 14:58:35 -0600 Subject: [PATCH 2/3] chore: formatting --- skills/workos-authkit-tanstack-start/SKILL.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/skills/workos-authkit-tanstack-start/SKILL.md b/skills/workos-authkit-tanstack-start/SKILL.md index 02d3d542..a46ce409 100644 --- a/skills/workos-authkit-tanstack-start/SKILL.md +++ b/skills/workos-authkit-tanstack-start/SKILL.md @@ -87,6 +87,7 @@ Default redirect URI: `http://localhost:3000/api/auth/callback` **authkitMiddleware MUST be configured or auth will fail silently.** **WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.** + ### If `start.ts` already exists Read the existing file first. Add `authkitMiddleware` to the existing `requestMiddleware` array (or create the array if missing). Preserve the existing export style. Do not rewrite the file from scratch. @@ -105,6 +106,7 @@ export const startInstance = createStart(() => ({ ``` **Two things matter here:** + 1. **Named export `startInstance`** — the build plugin generates `import type { startInstance }` from this file. A `default` export will cause a build error. 2. **`createStart` takes a function** returning the options object, not the options directly. `createStart({ ... })` will fail. @@ -238,6 +240,7 @@ pnpm build ``` Do not skip this step. If the build fails, fix the errors before finishing. Common causes: + - Stale route tree → re-run step 1 - Missing Vite types → re-run step 2 - Wrong import paths → check package name is `@workos/authkit-tanstack-react-start` From a33948f501aacf7781a7f63f40396e6f76db07bb Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Thu, 5 Mar 2026 14:59:24 -0600 Subject: [PATCH 3/3] chore: remove unused import --- src/lib/agent-interface.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/lib/agent-interface.ts b/src/lib/agent-interface.ts index 33a73bfb..b622056b 100644 --- a/src/lib/agent-interface.ts +++ b/src/lib/agent-interface.ts @@ -3,7 +3,6 @@ * Uses Claude Agent SDK directly with WorkOS MCP server */ -import path from 'path'; import { getPackageRoot } from '../utils/paths.js'; import { debug, logInfo, logWarn, logError, initLogFile, getLogFilePath } from '../utils/debug.js'; import type { InstallerOptions } from '../utils/types.js';