playbooks

home / skills / deckardger / tanstack-agent-skills / tanstack-start

tanstack-start skill

/skills/tanstack-start

This skill helps you implement TanStack Start best practices for full-stack React apps, improving security, SSR reliability, and deployment efficiency.

npx playbooks add skill deckardger/tanstack-agent-skills --skill tanstack-start

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
4.1 KB
---
name: tanstack-start-best-practices
description: TanStack Start best practices for full-stack React applications. Server functions, middleware, SSR, authentication, and deployment patterns. Activate when building full-stack apps with TanStack Start.
---

# TanStack Start Best Practices

Comprehensive guidelines for implementing TanStack Start patterns in full-stack React applications. These rules cover server functions, middleware, SSR, authentication, and deployment.

## When to Apply

- Creating server functions for data mutations
- Setting up middleware for auth/logging
- Configuring SSR and hydration
- Implementing authentication flows
- Handling errors across client/server boundary
- Organizing full-stack code
- Deploying to various platforms

## Rule Categories by Priority

| Priority | Category | Rules | Impact |
|----------|----------|-------|--------|
| CRITICAL | Server Functions | 5 rules | Core data mutation patterns |
| CRITICAL | Security | 4 rules | Prevents vulnerabilities |
| HIGH | Middleware | 4 rules | Request/response handling |
| HIGH | Authentication | 4 rules | Secure user sessions |
| MEDIUM | API Routes | 1 rule | External endpoint patterns |
| MEDIUM | SSR | 6 rules | Server rendering patterns |
| MEDIUM | Error Handling | 3 rules | Graceful failure handling |
| MEDIUM | Environment | 1 rule | Configuration management |
| LOW | File Organization | 3 rules | Maintainable code structure |
| LOW | Deployment | 2 rules | Production readiness |

## Quick Reference

### Server Functions (Prefix: `sf-`)

- `sf-create-server-fn` — Use createServerFn for server-side logic
- `sf-input-validation` — Always validate server function inputs
- `sf-method-selection` — Choose appropriate HTTP method
- `sf-error-handling` — Handle errors in server functions
- `sf-response-headers` — Customize response headers when needed

### Security (Prefix: `sec-`)

- `sec-validate-inputs` — Validate all user inputs with schemas
- `sec-auth-middleware` — Protect routes with auth middleware
- `sec-sensitive-data` — Keep secrets server-side only
- `sec-csrf-protection` — Implement CSRF protection for mutations

### Middleware (Prefix: `mw-`)

- `mw-request-middleware` — Use request middleware for cross-cutting concerns
- `mw-function-middleware` — Use function middleware for server functions
- `mw-context-flow` — Properly pass context through middleware
- `mw-composability` — Compose middleware effectively

### Authentication (Prefix: `auth-`)

- `auth-session-management` — Implement secure session handling
- `auth-route-protection` — Protect routes with beforeLoad
- `auth-server-functions` — Verify auth in server functions
- `auth-cookie-security` — Configure secure cookie settings

### API Routes (Prefix: `api-`)

- `api-routes` — Create API routes for external consumers

### SSR (Prefix: `ssr-`)

- `ssr-data-loading` — Load data appropriately for SSR
- `ssr-hydration-safety` — Prevent hydration mismatches
- `ssr-streaming` — Implement streaming SSR for faster TTFB
- `ssr-selective` — Apply selective SSR when beneficial
- `ssr-prerender` — Configure static prerendering and ISR

### Environment (Prefix: `env-`)

- `env-functions` — Use environment functions for configuration

### Error Handling (Prefix: `err-`)

- `err-server-errors` — Handle server function errors
- `err-redirects` — Use redirects appropriately
- `err-not-found` — Handle not-found scenarios

### File Organization (Prefix: `file-`)

- `file-separation` — Separate server and client code
- `file-functions-file` — Use .functions.ts pattern
- `file-shared-validation` — Share validation schemas

### Deployment (Prefix: `deploy-`)

- `deploy-env-config` — Configure environment variables
- `deploy-adapters` — Choose appropriate deployment adapter

## How to Use

Each rule file in the `rules/` directory contains:
1. **Explanation** — Why this pattern matters
2. **Bad Example** — Anti-pattern to avoid
3. **Good Example** — Recommended implementation
4. **Context** — When to apply or skip this rule

## Full Reference

See individual rule files in `rules/` directory for detailed guidance and code examples.

Overview

This skill provides practical best practices for building full-stack React applications with TanStack Start, TanStack Query, and TanStack Router. It focuses on server functions, middleware, SSR, authentication, error handling, file organization, and deployment patterns to produce secure, maintainable, and production-ready apps.

How this skill works

The skill inspects common full-stack patterns and recommends concrete rules for server functions, middleware composition, SSR strategies, and authentication flows. It organizes guidance by priority (critical, high, medium, low) and maps each recommendation to actionable patterns, examples, and when to apply them.

When to use it

  • When implementing server-side mutations and server functions for business logic.
  • When adding authentication, session handling, or protecting routes and APIs.
  • When configuring SSR, hydration, streaming, or prerender strategies.
  • When applying middleware for logging, auth, or context propagation.
  • When preparing code for production deployment and adapter selection.

Best practices

  • Create server functions (sf-) for mutations and validate all inputs with schemas before processing.
  • Keep secrets server-side, enforce CSRF protection for state-changing actions, and verify auth in server functions.
  • Compose request and function middleware to pass context cleanly and centralize cross-cutting concerns.
  • Use SSR selectively: load data on the server to avoid hydration mismatches and consider streaming for faster TTFB.
  • Separate server and client code (use .functions.ts pattern) and share validation schemas to avoid duplication.
  • Configure secure cookie settings, manage sessions carefully, and choose the right deployment adapter and env config.

Example use cases

  • Implementing a create/update resource flow using createServerFn with input validation and explicit HTTP methods.
  • Protecting admin routes with beforeLoad checks plus auth middleware that injects user context.
  • Configuring SSR for a product listing: server-load data, enable selective SSR for dynamic sections, and prerender stable pages.
  • Composing middleware to add logging, auth verification, and request-scoped DB connections.
  • Preparing a production build by choosing the right adapter, adding environment function-based config, and securing cookies.

FAQ

When should I choose streaming SSR?

Choose streaming SSR to improve time-to-first-byte for pages where incremental data can render progressively; avoid it if your UI requires fully synchronous rendering to prevent complexity.

How do I avoid hydration mismatches?

Load the same data shape on server and client, avoid rendering time-dependent values on first render, and use selective SSR where client-only parts are deferred.