TaylorDB + TanStack Start Template

A full-stack React template for building type-safe TaylorDB applications with TanStack Start, TanStack Router, Tailwind CSS, and shadcn/ui.

This template replaces the older React Router SPA + Express/tRPC split used by the legacy TaylorDB full-stack template with a single TanStack Start app. TaylorDB access runs on the server through TanStack Start server functions or server routes.

What This Template Provides

TanStack Start: SSR, routing, server functions, server routes, and Nitro output.
Type-safe TaylorDB access: @taylordb/query-builder with generated schema types.
Server-only data layer: database calls live in src/server/**, never in client components.
Modern UI: Tailwind CSS 4 and shadcn/ui components in src/components/ui.
AI-ready conventions: AGENTS.md explains where agents should put routes, server functions, repositories, and TaylorDB helpers.

Quick Start

pnpm install
pnpm dev

Build for production:

pnpm build
node .output/server/index.mjs

Project Structure

taylordb-tanstack-template/
├── src/
│   ├── routes/                 # TanStack Router file routes
│   │   ├── __root.tsx          # Root document shell
│   │   ├── index.tsx           # Home route
│   │   └── $.tsx               # Catch-all 404 route
│   ├── components/
│   │   ├── ui/                 # shadcn/ui components
│   │   ├── Header.tsx
│   │   └── ThemeToggle.tsx
│   ├── lib/
│   │   └── utils.ts            # shadcn cn() helper
│   ├── server/                 # Recommended server-only TaylorDB code
│   │   ├── taylordb.ts         # create per-request query builder
│   │   ├── repositories/       # table-level query functions
│   │   ├── services/           # business logic across repositories
│   │   └── *.functions.ts      # createServerFn operations
│   ├── routeTree.gen.ts        # generated by TanStack Router
│   ├── router.tsx
│   └── styles.css              # Tailwind + design tokens
├── docs/                       # shadcn and TaylorDB/TanStack guides
├── components.json             # shadcn config
├── package.json
└── vite.config.ts

src/server/** is the recommended location for TaylorDB code. The template may not include generated TaylorDB schema types until you connect a TaylorDB base and run the schema generator.

Tech Stack

App

React 19
TanStack Start
TanStack Router
Nitro output
Vite 8
TypeScript

Data

TaylorDB Query Builder (@taylordb/query-builder)
Generated TaylorDatabase schema types
TanStack Start server functions for app-facing data operations
TanStack Start server routes for raw HTTP endpoints and multipart/form-data

UI

Tailwind CSS 4
shadcn/ui
Radix UI primitives through the shadcn registry
Lucide icons

Recommended TaylorDB Pattern

TanStack Start does not need Express or tRPC for normal app data access. Use:

Server functions for typed reads and mutations called from loaders/components.
Server routes for raw HTTP APIs, webhooks, or file upload endpoints.
A server-only TaylorDB helper that reads the app_access_token cookie per request and constructs a fresh query builder.

Example helper:

// src/server/taylordb.ts
import { createQueryBuilder } from "@taylordb/query-builder";
import { getRequestHeader } from "@tanstack/react-start/server";
import type { TaylorDatabase } from "./taylordb/types";

function readCookie(name: string) {
  const header = getRequestHeader("cookie");
  if (!header) return null;

  for (const part of header.split(/;\s*/)) {
    const eq = part.indexOf("=");
    if (eq === -1) continue;
    if (part.slice(0, eq) === name) return decodeURIComponent(part.slice(eq + 1));
  }

  return null;
}

export function getTaylorDB() {
  const appAccessToken = readCookie("app_access_token");
  if (!appAccessToken) throw new Error("Unauthorized");

  return createQueryBuilder<TaylorDatabase>({
    baseUrl: process.env.TAYLORDB_BASE_URL!,
    baseId: process.env.TAYLORDB_SERVER_ID!,
    apiKey: appAccessToken,
  });
}

Example server function:

// src/server/users.functions.ts
import { createServerFn } from "@tanstack/react-start";
import { z } from "zod";
import { getTaylorDB } from "./taylordb";

export const getUsers = createServerFn({ method: "GET" }).handler(async () => {
  const qb = getTaylorDB();

  return qb
    .selectFrom("users")
    .select(["id", "name", "email"])
    .execute();
});

export const createUser = createServerFn({ method: "POST" })
  .inputValidator(z.object({ name: z.string().min(1), email: z.string().email() }))
  .handler(async ({ data }) => {
    const qb = getTaylorDB();

    return qb
      .insertInto("users")
      .values(data)
      .returning(["id", "name", "email"])
      .executeTakeFirst();
  });

Example route loader:

// src/routes/users.tsx
import { createFileRoute } from "@tanstack/react-router";
import { getUsers } from "@/server/users.functions";

export const Route = createFileRoute("/users")({
  loader: () => getUsers(),
  component: UsersPage,
});

function UsersPage() {
  const users = Route.useLoaderData();
  return <pre>{JSON.stringify(users, null, 2)}</pre>;
}

Server Routes

Use server routes when you need the raw Request object, a plain JSON endpoint, webhooks, or multipart form parsing:

// src/routes/api/users.ts
import { createFileRoute } from "@tanstack/react-router";
import { getTaylorDB } from "@/server/taylordb";

export const Route = createFileRoute("/api/users")({
  server: {
    handlers: {
      GET: async () => {
        const qb = getTaylorDB();
        const users = await qb.selectFrom("users").select(["id", "name"]).execute();
        return Response.json(users);
      },
      POST: async ({ request }) => {
        const formData = await request.formData();
        const qb = getTaylorDB();
        const file = formData.get("avatar");

        const attachments =
          file instanceof File
            ? await qb.uploadAttachments([{ file, name: file.name }])
            : [];

        return Response.json({ uploaded: attachments.length });
      },
    },
  },
});

Environment Variables

TaylorDB server-side code expects:

TAYLORDB_BASE_URL
TAYLORDB_SERVER_ID

The TaylorDB login flow must set an HttpOnly app_access_token cookie. Server functions and server routes read this cookie on each request.

Adding shadcn/ui Components

pnpm dlx shadcn@latest add button card input label textarea alert tabs select dropdown-menu

Do not add "use client" directives to app files. TanStack Start is not Next.js. If the shadcn registry inserts "use client", remove it from files under src/.

Documentation

AGENTS.md: implementation rules for AI agents.
docs/TAYLORDB_TANSTACK_START.md: TaylorDB with TanStack Start guide.
docs/SHADCN_COMPONENTS_GUIDE.md: shadcn component notes.
TanStack Start server functions
TanStack Start authentication server primitives

License

MIT

TaylorDB Full-Stack Template

A production-ready template for building modern, type-safe web applications with TaylorDB. Designed for AI-assisted development with comprehensive documentation and best practices built-in.

🎯 What This Template Provides

Full-Stack Setup: React frontend + Node.js backend in a monorepo
Type Safety: End-to-end TypeScript from database to UI
Modern UI: shadcn/ui components with Tailwind CSS
Type-Safe API: tRPC for seamless client-server communication
TaylorDB Integration: Query builder with generated types
AI-Ready: Comprehensive documentation for AI-assisted development

🚀 Quick Start

1. Install Dependencies

pnpm install

📁 Project Structure

taylordb-fullstack-template/
├── apps/
│   ├── client/                 # React frontend (Vite)
│   │   ├── src/
│   │   │   ├── components/ui/  # shadcn/ui components
│   │   │   ├── pages/          # Route pages
│   │   │   ├── lib/            # Utilities & tRPC client
│   │   │   └── index.css       # Design tokens
│   │   └── package.json
│   │
│   └── server/                 # Node.js backend
│       ├── taylordb/
│       │   ├── types.ts        # Generated schema types
│       │   └── query-builder.ts # Database operations
│       ├── router.ts           # tRPC API routes
│       └── package.json
│
├── docs/                       # Comprehensive guides
│   ├── TAYLORDB_QUERY_REFERENCE.md
│   └── SHADCN_COMPONENTS_GUIDE.md
│
├── AGENTS.md                   # AI agent instructions
└── taylordb.yml                # Deployment config

📚 Documentation

This template includes comprehensive documentation for both human and AI developers:

For AI Agents

AGENTS.md: Complete AI agent instructions
- Development workflow (Planning → Execution → Verification)
- Design guidelines for modern UIs
- Code organization best practices
- Type safety patterns
- Example implementations

For Developers

docs/TAYLORDB_QUERY_REFERENCE.md: Query builder reference
- All CRUD operations with examples
- Field type handling
- Advanced patterns (aggregations, pagination)
- Common pitfalls and solutions
docs/SHADCN_COMPONENTS_GUIDE.md: UI component guide
- Dashboard patterns
- Form examples
- Data tables
- Responsive design tips

🎨 Tech Stack

Frontend

React 19 with TypeScript
Vite 7 for fast builds
TailwindCSS 4 for styling
shadcn/ui for UI components
React Router v6 for routing
tRPC React Query for API calls

Backend

Node.js with TypeScript
Express 5 web server
tRPC 11 for type-safe APIs
Zod for validation
TaylorDB Query Builder for database

🎯 Key Features

✅ Full Type Safety

// Backend defines the API
export const appRouter = router({
  users: {
    getById: publicProcedure
      .input(z.object({ id: z.number() }))
      .query(async ({ input }) => { ... }),
  },
});

// Frontend gets full autocomplete
const { data: user } = trpc.users.getById.useQuery({ id: 1 });
//    ^? User | undefined (fully typed!)

✅ Modern UI Components

All components from shadcn/ui with:

Full dark mode support
Responsive design
Accessible by default
Customizable with Tailwind

✅ Database Integration

Type-safe queries with TaylorDB:

// Auto-generated types from your schema
export async function getAllUsers() {
  return await queryBuilder
    .selectFrom("users")
    .select(["id", "name", "email"])
    .execute();
}

🤖 AI-Assisted Development

This template is optimized for AI-assisted development:

Read AGENTS.md: Comprehensive instructions for AI agents
Follow the workflow: Planning → Execution → Verification
Use type safety: All examples use strict TypeScript
Reference docs: Query patterns, component examples, best practices

The AI agent will:

Understand your TaylorDB schema
Design appropriate color schemes
Build type-safe CRUD operations
Create modern, responsive UIs
Follow best practices automatically

🚢 Deployment

This template is designed to deploy to TaylorDB's platform using the included taylordb.yml configuration.

Environment Variables Required:

TAYLORDB_BASE_URL
TAYLORDB_SERVER_ID

📖 Usage Examples

1. Add a New Feature

Create database functions in apps/server/taylordb/query-builder.ts
Expose via tRPC in apps/server/router.ts
Build UI in apps/client/src/pages/
Add route in apps/client/src/main.tsx

2. Add shadcn/ui Component

pnpm dlx shadcn@latest add <component-name>

Example:

pnpm dlx shadcn@latest add table dialog toast

3. Customize Design

Edit apps/client/src/index.css to change colors, fonts, and spacing.

🔗 Resources

shadcn/ui: https://ui.shadcn.com/
tRPC: https://trpc.io/
TaylorDB: https://taylordb.ai/
Tailwind CSS: https://tailwindcss.com/

📄 License

MIT - Use freely for any project!

Built for modern, type-safe full-stack development with AI assistance ✨

Name		Name	Last commit message	Last commit date
.vscode		.vscode
docs		docs
public		public
src		src
.cta.json		.cta.json
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
components.json		components.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
taylordb.yml		taylordb.yml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation