dotfiles/dot_agents/skills/tanstack-start-best-practices/rules/deploy-adapters.md

deploy-adapters: Choose Appropriate Deployment Adapter

Priority: LOW

Explanation

TanStack Start uses deployment adapters to target different hosting platforms. Each adapter optimizes the build output for its platform's runtime, edge functions, and static hosting capabilities.

Bad Example

// Not configuring adapter - using defaults may not match your host
// app.config.ts
export default defineConfig({
  // No adapter specified
  // May not work correctly on your deployment platform
})

// Or using wrong adapter for platform
export default defineConfig({
  server: {
    preset: 'node-server',  // But deploying to Vercel Edge
  },
})

Good Example: Vercel Deployment

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'vercel',
    // Vercel-specific options
  },
})

// vercel.json (optional, for customization)
{
  "framework": null,
  "buildCommand": "npm run build",
  "outputDirectory": ".output"
}

Good Example: Cloudflare Pages

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'cloudflare-pages',
  },
})

// wrangler.toml
name = "my-tanstack-app"
compatibility_date = "2024-01-01"
pages_build_output_dir = ".output/public"

// For Cloudflare Workers (full control)
export default defineConfig({
  server: {
    preset: 'cloudflare',
  },
})

Good Example: Netlify

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'netlify',
  },
})

// netlify.toml
[build]
  command = "npm run build"
  publish = ".output/public"

[functions]
  directory = ".output/server"

Good Example: Node.js Server

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'node-server',
    // Optional: customize port
  },
})

// Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY .output .output
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

// Or run directly
// node .output/server/index.mjs

Good Example: Static Export (SPA)

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'static',
    prerender: {
      routes: ['/'],
      crawlLinks: true,
    },
  },
})

// Output: .output/public (static files only)
// Host anywhere: GitHub Pages, S3, any static host

Good Example: AWS Lambda

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'aws-lambda',
  },
})

// Deploy with SST, Serverless Framework, or AWS CDK
// serverless.yml example:
service: my-tanstack-app
provider:
  name: aws
  runtime: nodejs20.x
functions:
  app:
    handler: .output/server/index.handler
    events:
      - http: ANY /
      - http: ANY /{proxy+}

Good Example: Bun Runtime

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  server: {
    preset: 'bun',
  },
})

// Run with: bun .output/server/index.mjs

Adapter Comparison

Adapter	Runtime	Edge	Static	Best For
vercel	Node/Edge	Yes	Yes	Vercel hosting
cloudflare-pages	Workers	Yes	Yes	Cloudflare Pages
cloudflare	Workers	Yes	No	Cloudflare Workers
netlify	Node	Yes	Yes	Netlify hosting
node-server	Node	No	No	Docker, VPS, self-host
static	None	No	Yes	Any static host
aws-lambda	Node	No	No	AWS serverless
bun	Bun	No	No	Bun runtime

Context

• Adapters transform output for target platform
• Edge adapters have API limitations (no file system, etc.)
• Static preset requires all routes to be prerenderable
• Test locally with npm run build && npm run preview
• Check platform docs for runtime-specific constraints
• Some platforms auto-detect TanStack Start (no adapter needed)