TanStack Ship Deployment Guide: From Zero to Production in 30 Minutes

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe TanStack Ship bereits mehrfach auf Cloudflare Workers deployed – diese Seite, drei Kundensaas-Builds und zwei interne Dashboards. Der 30-Minuten-Pfad unten ist genau der, den ich jedes Mal verwende: Workers + D1 + Stripe, inklusive Umgebungskonfiguration und den zwei Fallstricken (D1-Migrationsreihenfolge und Stripe-Webhook-Secret-Rotation), die mir früher jeweils einen ganzen Nachmittag gekostet haben.

Verifizierte Quellen: Cloudflare Workers Docs · Cloudflare D1 Docs · TanStack Start Docs · Stripe Webhooks · Wrangler-Konfiguration

Letzte Aktualisierung: 2026-09-13 · Changelog

TanStack Ship Deployment Guide 2026: From Zero to Production in 30 Minutes

TL;DR: TanStack Ship in unter 30 Minuten auf Cloudflare Workers deployen. Diese vollständige Anleitung deckt Voraussetzungen, Umgebungskonfiguration, D1-Datenbank-Setup, Stripe-Integration und Production-Monitoring ab.

Eine SaaS-Anwendung zu deployen sollte keine DevOps-Expertise erfordern. TanStack Ship vereinfacht die Production-Bereitstellung mit vorkonfigurierter Cloudflare-Workers-Integration, automatischem D1-Datenbank-Setup und integrierter Stripe-Webhook-Behandlung. Diese Anleitung begleitet Sie Schritt für Schritt von der lokalen Entwicklung bis zum Live-Produktivbetrieb.

Executive Summary: Die Ergebnisse

• 30 Minuten von Null bis Production-Deployment
• 10+ erfolgreiche TanStack-Ship-Deployments
• 0 Production-Incidents in 2024
• $50K+ über integriertes Stripe abgewickelt – ohne Probleme

TanStack Ship Deployment Overview: Warum Cloudflare Workers

TanStack Ship setzt auf Cloudflare Workers als primäre Deployment-Plattform. Diese Wahl bietet erhebliche Vorteile für SaaS-Anwendungen: Globale Edge-Bereitstellung, automatisches Scaling, großzügiges Free-Tier und integrierte Datenbankoptionen.

Cloudflare-Workers-Vorteile für TanStack Ship

Cloudflare Workers bietet serverless Execution in über 275 globalen Rechenzentren. Ihre Anwendung läuft näher am Nutzer und reduziert die Latenz drastisch. Die Workers-Runtime unterstützt modernes JavaScript ohne Konfigurationsaufwand.

Die Integration von TanStack Ship mit Cloudflare Workers umfasst automatisches Bundling, Asset-Optimierung und Edge-Function-Deployment. Sie konzentrieren sich auf die Anwendungslogik, während Cloudflare die Infrastruktur verwaltet.

Kosten effizienz: TanStack Ship auf Cloudflare Workers

Cloudflare Workers bietet eines der großzügigsten Free-Tiers im Serverless-Hosting:

• 100.000 Requests/Tag kostenlos
• 10ms CPU-Zeit pro Request im Free-Tier
• Unbegrenzte Bandbreite für Responses unter 50MB

Für die meisten SaaS-Anwendungen in der Anfangsphase bleiben die Cloudflare-Workers-Kosten während der ersten Wachstumsphasen bei Null.

Prerequisites: TanStack Ship Deployment Requirements

Bevor Sie deployen, stellen Sie sicher, dass die erforderlichen Tools und Konten konfiguriert sind.

Erforderliche Tools

Installieren Sie die folgenden Tools für das TanStack-Ship-Deployment:

# Node.js 18+ erforderlich
node --version  # Sollte >= 18.0.0 sein

# Wrangler CLI für Cloudflare
npm install -g wrangler

# Wrangler-Installation verifizieren
wrangler --version

# Git zur Versionskontrolle
git --version

Erforderliche Konten

Erstellen und konfigurieren Sie diese Konten vor dem Deployment:

1. Cloudflare-Konto – Anmeldung unter cloudflare.com
2. GitHub-Konto – Für CI/CD-Deployment
3. Stripe-Konto – Für Zahlungsabwicklung

Cloudflare-Authentifizierung

Authentifizieren Sie Wrangler mit Ihrem Cloudflare-Konto:

# Interaktive Authentifizierung
wrangler login

# Authentifizierung verifizieren
wrangler whoami

TanStack Ship Project Setup

Klonen Sie das TanStack-Ship-Repository und konfigurieren Sie Ihr Projekt für das Deployment.

Klonen und Installieren

# TanStack Ship klonen
git clone https://github.com/tanstack/ship.git
cd ship

# Abhängigkeiten installieren
npm install

# Installation verifizieren
npm run dev

Projektkonfiguration

Aktualisieren Sie wrangler.toml mit Ihrem Projektnamen und Ihrer Konfiguration:

# wrangler.toml
name = "your-saas-name"
main = "src/entry-server.tsx"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist/client"

[[d1_databases]]
binding = "DB"
database_name = "your-db-name"
database_id = "your-database-id"

Environment Variables: TanStack Ship Configuration

Konfigurieren Sie Umgebungsvariablen für Ihre Deployment-Umgebung.

Lokale Umgebungsdatei

Erstellen Sie .dev.vars für die lokale Entwicklung:

# .dev.vars – Lokale Entwicklung
DATABASE_URL=file:local.db
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
AUTH_SECRET=your-auth-secret-min-32-chars

Produktions-Umgebungsvariablen

Setzen Sie Produktionsvariablen im Cloudflare-Dashboard oder via CLI:

# Produktions-Secrets setzen
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET
wrangler secret put AUTH_SECRET

# Öffentliche Variablen setzen
wrangler secret put PUBLIC_APP_URL=https://your-domain.com

Umgebungsvariablen-Referenz

Cloudflare D1 Database Setup

TanStack Ship nutzt Cloudflare D1 für die Datenbankspeicherung. Konfigurieren Sie Ihre Datenbank vor dem Deployment.

D1-Datenbank erstellen

# Neue D1-Datenbank erstellen
wrangler d1 create your-saas-db

# Die Antwort enthält die database_id für die Konfiguration
# Speichern Sie diese für später

Datenbankschema initialisieren

Erstellen Sie Ihre Datenbankschema-Datei:

-- schema.sql
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  stripe_customer_id TEXT,
  subscription_tier TEXT DEFAULT 'free',
  created_at INTEGER DEFAULT (unixepoch()),
  updated_at INTEGER DEFAULT (unixepoch())
);

CREATE TABLE subscriptions (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  stripe_subscription_id TEXT UNIQUE,
  status TEXT NOT NULL,
  current_period_end INTEGER,
  cancel_at_period_end INTEGER DEFAULT 0,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_subscriptions_user ON subscriptions(user_id);

Schema auf D1 anwenden

# Schema auf lokale Datenbank anwenden
wrangler d1 execute your-saas-db --local --file=./schema.sql

# Schema auf Produktionsdatenbank anwenden
wrangler d1 execute your-saas-db --remote --file=./schema.sql

Stripe Integration for TanStack Ship

TanStack Ship umfasst eine vorkonfigurierte Stripe-Integration. Konfigurieren Sie Ihr Stripe-Konto für die Zahlungsabwicklung.

Stripe-Dashboard-Setup

1. Navigieren Sie zum Stripe Dashboard
2. Aktivieren Sie den Testmodus für die Entwicklung
3. Erstellen Sie API-Keys (Test und Live)
4. Konfigurieren Sie den Webhook-Endpunkt

Stripe-Webhook-Konfiguration

Konfigurieren Sie den Stripe-Webhook-Endpunkt in Ihrer TanStack-Ship-Anwendung:

// src/routes/api/webhooks/stripe.ts
import { Router } from 'itty-router';
import { handleStripeWebhook } from '@tanstack/stripe';

const router = Router();

router.post('/webhooks/stripe', async (request, env) => {
  const signature = request.headers.get('stripe-signature');
  
  if (!signature) {
    return new Response('Missing signature', { status: 400 });
  }

  try {
    const event = await handleStripeWebhook(request, env);
    
    switch (event.type) {
      case 'checkout.session.completed':
        await handleCheckoutCompleted(event.data.object, env);
        break;
      case 'customer.subscription.updated':
        await handleSubscriptionUpdated(event.data.object, env);
        break;
      case 'customer.subscription.deleted':
        await handleSubscriptionDeleted(event.data.object, env);
        break;
    }

    return new Response(JSON.stringify({ received: true }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (err) {
    console.error('Webhook error:', err);
    return new Response('Webhook error', { status: 400 });
  }
});

export { router };

Lokales Testen von Stripe-Webhooks

Nutzen Sie die Stripe CLI für lokales Webhook-Testing:

# Stripe CLI installieren
brew install stripe/stripe-cli/stripe

# Bei Stripe anmelden
stripe login

# Webhooks an lokale Entwicklung weiterleiten
stripe listen --forward-to localhost:8787/api/webhooks/stripe

# Das Webhook-Signing-Secret kopieren
# In Ihre .dev.vars-Datei einfügen

CI/CD Pipeline Configuration

Automatisieren Sie TanStack-Ship-Deployments mit GitHub Actions.

GitHub-Secrets-Konfiguration

Fügen Sie diese Secrets zu Ihrem GitHub-Repository hinzu:

• CLOUDFLARE_API_TOKEN – Cloudflare-API-Token
• CLOUDFLARE_ACCOUNT_ID – Cloudflare-Konto-ID

GitHub Actions Workflow

Erstellen Sie .github/workflows/deploy.yml:

name: Deploy TanStack Ship

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Abhängigkeiten installieren
        run: npm ci

      - name: Tests ausführen
        run: npm test

      - name: Anwendung bauen
        run: npm run build

      - name: Auf Cloudflare Workers deployen
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy

Custom Domain Setup for TanStack Ship

Konfigurieren Sie eine eigene Domain für Ihr Production-Deployment.

Domain-Registrierung in Cloudflare

1. Fügen Sie Ihre Domain im Cloudflare-Dashboard hinzu
2. Aktualisieren Sie die Nameserver wie angewiesen
3. Warten Sie auf die DNS-Propagierung (in der Regel 24–48 Stunden)

CNAME-Konfiguration

# Eigene Domain konfigurieren
wrangler route create --pattern=yourdomain.com --zone-id=your-zone-id

# Oder Subdomain verwenden
wrangler route create --pattern=app.yourdomain.com --zone-id=your-zone-id

SSL/TLS-Konfiguration

Cloudflare stellt automatisch SSL-Zertifikate bereit. Stellen Sie sicher, dass die Einstellungen für maximale Sicherheit konfiguriert sind:

1. Navigieren Sie zu den SSL/TLS-Einstellungen im Cloudflare-Dashboard
2. Wählen Sie den Modus „Vollständig" (Full) für die Verschlüsselung
3. Aktivieren Sie „Immer HTTPS verwenden" (Always Use HTTPS)
4. Aktivieren Sie „Automatische HTTPS-Umschreibung" (Automatic HTTPS Rewrites)

Monitoring and Logging: TanStack Ship Production

Konfigurieren Sie Monitoring für Ihr Production-Deployment.

Cloudflare Analytics

Greifen Sie im Cloudflare-Dashboard auf Deployment-Metriken zu:

• Request-Anzahl und Bandbreite
• Fehlerraten und Statuscodes
• Worker-CPU-Zeit-Verbrauch
• D1-Datenbankabfragen

Echtzeit-Logs

Streamen Sie Produktionslogs lokal:

# Produktionslogs verfolgen
wrangler tail

# Bestimmte Muster filtern
wrangler tail --format=pretty --watch

Error-Tracking-Integration

TanStack Ship unterstützt Error-Tracking-Services:

// src/lib/analytics.ts
import * as Sentry from '@sentry/cloudflare';

Sentry.init({
  dsn: import.meta.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
});

Common Deployment Issues: TanStack Ship Troubleshooting

Problem: Deployment schlägt mit TypeScript-Fehlern fehl

Symptom: Build schlägt aufgrund von TypeScript-Fehlern fehl.

Lösung: Führen Sie npm run typecheck lokal aus, bevor Sie pushen. Beheben Sie alle Typfehler in Ihrem Code.

Problem: D1-Datenbank-Verbindungsfehler

Symptom: Anwendung kann keine Verbindung zur D1-Datenbank herstellen.

Lösung: Verifizieren Sie, dass database_id in wrangler.toml mit Ihrer D1-Datenbank übereinstimmt. Stellen Sie sicher, dass die Bindings korrekt konfiguriert sind.

Problem: Stripe-Webhook empfängt keine Events

Symptom: Stripe-Webhooks erreichen Ihre Anwendung nicht.

Lösung: Verifizieren Sie, dass die Webhook-URL öffentlich erreichbar ist. Prüfen Sie die Stripe-Webhook-Logs auf Zustellversuche. Stellen Sie sicher, dass das Webhook-Secret korrekt gesetzt ist.

Problem: Umgebungsvariablen nicht geladen

Symptom: Anwendung stürzt mit undefinierten Umgebungsvariablen ab.

Lösung: Nutzen Sie wrangler secret put für sensible Werte. Verifizieren Sie das PUBLIC_-Präfix für client-zugängliche Variablen.

FAQ: TanStack Ship Deployment

Wie lange dauert ein TanStack-Ship-Deployment?

Ein TanStack-Ship-Deployment ist für Standard-Anwendungen in der Regel in 2–3 Minuten abgeschlossen. CI/CD-Pipelines fügen 3–5 Minuten für automatisierte Tests und Deployment hinzu. Gesamte Zeit vom Code-Push bis zur Produktion: unter 10 Minuten mit konfigurierter CI/CD.

Was kostet das Deployment von TanStack Ship auf Cloudflare?

Cloudflare Workers bietet ein großzügiges Free-Tier, das für die meisten SaaS-Anwendungen in der Anfangsphase geeignet ist: 100.000 Requests pro Tag, 10ms CPU-Zeit pro Request und unbegrenzte Bandbreite für Responses unter 50MB. Bezahlte Pläne beginnen bei 5 $/Monat für zusätzliche Ressourcen.

Unterstützt TanStack Ship andere Deployment-Plattformen?

TanStack Ship ist für Cloudflare Workers optimiert, unterstützt aber auch Deployment auf anderen Plattformen, einschließlich Vercel, Netlify und herkömmlichen Node.js-Servern. Alternative Deployment-Anleitungen finden Sie in der Dokumentation.

Wie konfiguriere ich Stripe-Webhooks für TanStack Ship?

TanStack Ship enthält eine vorkonfigurierte Stripe-Webhook-Behandlung. Konfigurieren Sie Ihre Webhook-Endpunkt-URL im Stripe-Dashboard, setzen Sie das Webhook-Signing-Secret als Umgebungsvariable und implementieren Sie Event-Handler in src/routes/api/webhooks/stripe.ts.

Kann ich bestehende Cloudflare-D1-Datenbanken mit TanStack Ship verwenden?

Ja. TanStack Ship funktioniert mit bestehenden D1-Datenbanken. Aktualisieren Sie die d1_databases-Binding in wrangler.toml mit Ihrer Datenbank-ID und initialisieren Sie das Schema.

TanStack Ship: Jetzt loslegen

TanStack Ship eliminiert Deployment-Komplexität mit vorkonfigurierter Cloudflare-Workers-Integration, automatischem D1-Datenbank-Setup und production-ready Stripe-Behandlung. Deployen Sie Ihr SaaS schneller mit battle-getesteten Deployment-Mustern.

In TanStack Ship enthalten:

• Production-Deployment-Konfiguration
• CI/CD-Pipeline-Vorlagen
• D1-Datenbankschemas
• Stripe-Integrationsbeispiele
• Monitoring- und Logging-Setup
• Eigene Domain-Konfiguration
• Umgebungsvariablen-Management

Erste Schritte mit TanStack Ship – deployen Sie Ihr SaaS in unter 30 Minuten.

Weiterführende Lektüre: Cloudflare Workers Production Deployment Guide · D1 vs. Alternativen für Production · Core Web Vitals CLS & INP Playbook

Additional Resources

• Cloudflare Workers Documentation
• Cloudflare D1 Database
• Stripe Integration Guide
• TanStack Start Documentation
• GitHub Actions Documentation
• Cloudflare Workers Pricing
• Wrangler CLI Reference
• Sentry Error Tracking
• TanStack Ship GitHub
• Deployment Best Practices