blog

Imported from tanan/blog (AGENTS.md). Install upstream with npx skills add tanan/blog. Copyright stays with the author.

Skill Loading

Before substantial work:

• Skill check: run npx @tanstack/intent@latest list, or use skills already listed in context.
• Skill guidance: if one local skill clearly matches the task, run npx @tanstack/intent@latest load <package>#<skill> and follow the returned SKILL.md.
• Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
• Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.

Project: blog

Blank TanStack Start app, kept intentionally minimal: one root route, one index route, no UI framework, no devtools, no test runner, no example components.

Stack

• Framework: TanStack Start (React) — @tanstack/react-start, @tanstack/react-router, @tanstack/router-plugin
• Runtime: React 19 + React DOM 19
• Build: Vite 8 + @vitejs/plugin-react
• Language: TypeScript 5
• Package manager: bun (lockfile: bun.lock)
• Toolchain: biome (biome.json, scripts: format, lint, check)
• Routing: filesystem (src/routes/), generated tree at src/routeTree.gen.ts

How this project was scaffolded

Run from /Users/anan/zidai/git/tanan/ (or any scratch dir):

npx @tanstack/cli@latest create blog --agent --package-manager bun --toolchain biome

Follow-ups inside the project:

npx @tanstack/intent@latest install   # writes the intent-skills block above
npx @tanstack/intent@latest list      # discover available skills before substantial changes

The CLI scaffold landed in a nested blog/blog/ directory. Its inner .git was deleted and its contents moved up into the working repo at /Users/anan/zidai/git/tanan/blog/. The pre-existing parent .git was preserved.

What the CLI gave us, and what was removed

The @tanstack/cli --agent mode bundles defaults that the user brief explicitly rejected ("blank, no extra integrations or feature scaffolding"). The following were stripped after the initial scaffold:

Re-add any of these intentionally if the project grows beyond "blank".

Commands

bun install         # install deps
bun run dev         # vite dev on http://localhost:3000
bun run build       # production build (client + ssr -> dist/)
bun run preview     # preview built app
bun run check       # biome format + lint check
bun run format      # biome format only
bun run lint        # biome lint only

Project layout

.
├── AGENTS.md              # this file
├── biome.json             # biome config (tab indent, double quotes)
├── bun.lock               # bun lockfile
├── package.json
├── public/                # static assets (favicon, logos, manifest, robots)
├── src/
│   ├── router.tsx         # createTanStackRouter factory + Register declaration
│   ├── routeTree.gen.ts   # generated by @tanstack/router-plugin (do not edit)
│   └── routes/
│       ├── __root.tsx     # document shell (HeadContent, Outlet, Scripts)
│       └── index.tsx      # "/" route
├── tsconfig.json
└── vite.config.ts         # tanstackStart() + viteReact() (Start plugin first)

Environment variables

• None required for the blank app.
• TanStack Start convention: client-readable env vars must be prefixed VITE_ (Vite exposes them via import.meta.env). Server-only secrets stay unprefixed and must only be referenced inside createServerFn / *.server.ts modules.

Deployment notes (portable setup)

This app is intentionally host-agnostic. No platform adapter is wired in. To deploy:

1. Run bun run build — produces dist/client/ and dist/server/server.js.
2. The default Start build outputs a Node-compatible SSR server entry. A bare-bones run is node dist/server/server.js (Bun also works: bun dist/server/server.js).
3. For Cloudflare / Netlify / Vercel / Bun / Node-Docker, consult the start-core/deployment Intent skill (npx @tanstack/intent@latest load @tanstack/start-client-core#start-core/deployment) before adding host-specific config.
4. Keep deployment config out of the repo until a target is chosen — adding a wrong adapter is harder to undo than adding the right one later.

Key architectural decisions

• bun + biome were the user's explicit toolchain choices and are baked into both package.json scripts and biome.json. Do not swap to npm/pnpm/eslint/prettier without confirming.
• No UI framework. __root.tsx renders <html>/<body> with no className. Add Tailwind / CSS Modules / vanilla CSS only when there's a concrete need.
• No devtools, no test runner. Re-add when there's a real reason (active debugging, first test).
• Filesystem routing (not virtual). New routes go in src/routes/. The router-plugin regenerates routeTree.gen.ts on dev/build.
• Start plugin must come before React plugin in vite.config.ts (route generation + server-fn compilation depend on this order).

Known gotchas

• verbatimModuleSyntax removed from tsconfig.json. The CLI scaffold turned it on, but the start-core skill flags this as HIGH-severity: it can leak server-only modules into the client bundle. Keep it off.
• biome schema URL is pinned. biome.json $schema was bumped from the scaffold's 2.2.4 to 2.4.5 to match the installed @biomejs/biome version. Bump when upgrading biome.
• Nested git after scaffolding. npx @tanstack/cli create initializes its own .git inside the new project dir. If scaffolding into an existing repo, delete the inner .git (or scaffold into a scratch dir and merge files in).
• Two path aliases (#/* and @/*) point at src/ in tsconfig.json, but only #/* is mirrored under package.json#imports (used at runtime by Node's subpath imports). Pick one convention before this matters.

Next steps

• Decide on a deployment target before the first deploy; load the deployment Intent skill at that point.
• Add a styling approach when the first real UI lands.
• Re-add a test runner (vitest + jsdom + Testing Library) when writing the first test.
• Wire @tanstack/react-router-devtools when debugging routing becomes a real need.
• Initialize a .env.example once any env vars exist (none today).