wcygan-net-stack - SKILL.md Agent Skill

name: wcygan-net-stack description: Project stack guide for wcygan.net covering Deno runtime, TanStack Start framework, MDX markdown rendering, and Mermaid diagram components. Auto-loads when working on routes, components, blog posts, MDX config, Vite config, mermaid diagrams, or build/deploy. Keywords: deno, tanstack, tanstack start, tanstack router, mdx, markdown, mermaid, diagram, vite, nitro, blog post, route, shiki

wcygan.net Stack Guide

This skill provides project-specific knowledge for the wcygan.net blog, covering the four core subsystems. Load the appropriate reference for detailed patterns.

Quick Reference

Area	Entry Point	Reference
Deno runtime & build	`deno.json`, `package.json`, `vite.config.ts`	deno.md
TanStack Start routing & SSR	`src/routes/`, `src/router.tsx`	tanstack-start.md
MDX markdown pipeline	`vite.config.ts` MDX plugin, `src/posts/`	mdx-pipeline.md
Mermaid diagrams	`src/diagrams/`, `scripts/render-diagrams.mjs`	mermaid-diagrams.md

Critical Gotchas

Loaders must return serializable data only. Never return React components, functions, or class instances from TanStack Router loaders — they get JSON-serialized for SSR hydration. Load MDX components client-side via useEffect.
Never use ref.current.innerHTML in React components. Use dangerouslySetInnerHTML via state instead. Direct DOM mutation breaks React's reconciler during hydration (causes removeChild errors).
The $slug route is a catch-all. It matches everything including /rss.xml and /favicon.ico. The beforeLoad guard rejects slugs containing dots to let static files through.
Mermaid must be dynamically imported. It's browser-only and ~2MB. Use import('mermaid') at runtime, never a top-level import. The ESM alias in vite.config.ts points to the optimized build.
MDX frontmatter uses frontmatter not metadata. The remark-mdx-frontmatter plugin exports frontmatter under module.frontmatter, unlike the old MDsveX which used module.metadata.