Deploy to Netlify

​

Prerequisites

• A Netlify account (sign up here)
• Node.js and pnpm (or npm/yarn) installed
• A TanStack Start application

​

Quick Start with CLI

​

1. Install Plugin

pnpm add --save-dev @netlify/vite-plugin-tanstack-start

​

2. Update Vite Config

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import netlify from '@netlify/vite-plugin-tanstack-start'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart(),
    netlify(), // Add anywhere in the array
    viteReact(),
  ],
})

​

3. Deploy

px netlify deploy

• Link or create a new site
• Configure build settings (automatically detected)

px netlify deploy --prod

​

Benefits of the Netlify Plugin

• Automatic build configuration for Netlify deployment
• Full platform emulation in local development
• Edge Functions support out of the box
• Image optimization integration
• Environment variables handling

​

Manual Configuration

[build]
  command = "vite build"
  publish = "dist/client"

[dev]
  command = "vite dev"
  port = 3000

​

Environment Variables

​

In Netlify Dashboard

1. Go to Site settings > Environment variables
2. Add your variables
3. Choose the deploy context (production, preview, or branch)

​

In netlify.toml

[context.production.environment]
  API_URL = "https://api.production.com"
  NODE_ENV = "production"

[context.deploy-preview.environment]
  API_URL = "https://api.staging.com"

​

Accessing Variables

export const getServerData = async () => {
  const apiUrl = process.env.API_URL
  return { apiUrl }
}

​

Deployment Methods

​

Git-Based Deployment

1. Push your code to GitHub, GitLab, or Bitbucket
2. Connect your repository in the Netlify dashboard
3. Netlify automatically deploys on every push

• Automatic deployments on git push
• Deploy previews for pull requests
• Rollback to any previous deployment

​

CLI Deployment

# Deploy to draft URL
npx netlify deploy

# Deploy to production
npx netlify deploy --prod

​

Continuous Deployment

• You push to your main branch (production)
• You open a pull request (deploy preview)
• You push to any branch (branch deploys, if enabled)

​

Build Configuration

​

Build Commands

[build]
  command = "pnpm build"
  publish = "dist/client"
  
[build.environment]
  NODE_VERSION = "20"
  NPM_FLAGS = "--prefix=/dev/null"

​

Post-Processing

[build.processing]
  skip_processing = false
[build.processing.css]
  bundle = true
  minify = true
[build.processing.js]
  bundle = true
  minify = true
[build.processing.html]
  pretty_urls = true
[build.processing.images]
  compress = true

​

Advanced Features

​

Netlify Edge Functions

​

Headers Configuration

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    Content-Security-Policy = "default-src 'self'"

​

Redirects and Rewrites

[[redirects]]
  from = "/old-path"
  to = "/new-path"
  status = 301

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200

​

Split Testing

[[redirects]]
  from = "/*"
  to = "/branch-a/:splat"
  status = 200
  conditions = {Cookie=["ab_test=a"]}

[[redirects]]
  from = "/*"
  to = "/branch-b/:splat"
  status = 200
  conditions = {Cookie=["ab_test=b"]}

​

Deploy Previews

1. Open a pull request
2. Netlify builds and deploys a preview
3. Preview URL is posted as a comment
4. Test changes before merging

​

Configure Deploy Previews

[context.deploy-preview]
  command = "pnpm build:preview"
  
[context.deploy-preview.environment]
  HUGO_ENV = "staging"

​

Custom Domains

​

Add a Custom Domain

1. Go to Site settings > Domain management
2. Click Add custom domain
3. Follow DNS configuration instructions

​

Domain Configuration in netlify.toml

[[redirects]]
  from = "https://www.example.com/*"
  to = "https://example.com/:splat"
  status = 301
  force = true

​

Performance Optimization

​

Asset Optimization

• Image compression
• CSS and JavaScript minification
• Brotli compression

​

Caching

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

​

Monitoring and Analytics

1. Go to Analytics in your site dashboard
2. Enable Netlify Analytics (paid feature)
3. View traffic, top pages, and more

​

Resources

• Netlify Documentation
• TanStack Start on Netlify Guide
• Netlify CLI Documentation
• Netlify Plugin Repository

​

Troubleshooting

​

Build Failures

• Check the build logs in Netlify dashboard
• Verify Node.js version: add NODE_VERSION = "20" to build environment
• Ensure all dependencies are in package.json
• Clear cache and retry: Deploys > Trigger deploy > Clear cache and deploy site

​

Function Errors

• Check Functions tab in Netlify dashboard for logs
• Verify environment variables are set correctly
• Test locally with the Netlify plugin’s emulation

​

Deploy Preview Issues

• Check Site settings > Build & deploy > Deploy contexts
• Ensure deploy previews are enabled
• Verify branch deploy settings

​

Domain Issues

• Verify DNS records are configured correctly
• Wait for DNS propagation (can take up to 48 hours)
• Check Site settings > Domain management for status
• Ensure domain is not already used by another Netlify site