create-fate 1.0.3 → 1.3.0

package/templates/fate/cloudflare/server/src/lib/auth.ts

@@ -0,0 +1,66 @@
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { admin, username } from 'better-auth/plugins';
+import { db } from '../../db/db.ts';
+import schema from '../../db/schema.ts';
+import { trustedOrigins } from './origins.ts';
+
+const defaultSecret = 'fate-cloudflare-development-secret';
+const betterAuthDefaultSecret = 'better-auth-secret-12345678901234567890';
+
+const resolveSecret = (secret?: string) => {
+  const value =
+    secret ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+      ?.BETTER_AUTH_SECRET;
+
+  return value && value !== betterAuthDefaultSecret ? value : defaultSecret;
+};
+
+const createAuthInstance = (baseURL: string, secret: string) =>
+  betterAuth({
+    advanced: {
+      database: {
+        generateId: false,
+      },
+    },
+    basePath: '/api/auth',
+    baseURL,
+    database: drizzleAdapter(db, {
+      provider: 'sqlite',
+      schema,
+    }),
+    emailAndPassword: {
+      autoSignIn: true,
+      enabled: true,
+      maxPasswordLength: 128,
+      minPasswordLength: 8,
+    },
+    plugins: [admin(), username()],
+    secret,
+    session: {
+      cookieCache: {
+        enabled: true,
+        maxAge: 15 * 24 * 60 * 60,
+      },
+    },
+    telemetry: { enabled: false },
+    trustedOrigins,
+  });
+
+const authByBaseURL = new Map<string, ReturnType<typeof createAuthInstance>>();
+
+export const createAuth = (baseURL = 'http://localhost:8787', secret?: string) => {
+  const resolvedSecret = resolveSecret(secret);
+  const cacheKey = `${baseURL}\0${resolvedSecret}`;
+  const existing = authByBaseURL.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+
+  const auth = createAuthInstance(baseURL, resolvedSecret);
+  authByBaseURL.set(cacheKey, auth);
+  return auth;
+};
+
+export const auth = createAuth();

package/templates/fate/cloudflare/server/src/lib/origins.ts

@@ -0,0 +1,17 @@
+const localDevOriginPattern = /^https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?$/;
+
+export const clientOrigin = 'http://localhost:6001';
+
+export const resolveCorsOrigin = (origin: string | null) => {
+  if (!origin) {
+    return null;
+  }
+
+  if (origin === clientOrigin || localDevOriginPattern.test(origin)) {
+    return origin;
+  }
+
+  return null;
+};
+
+export const trustedOrigins = [clientOrigin, 'http://localhost:*', 'http://127.0.0.1:*'];

package/templates/fate/cloudflare/server/src/router.ts

@@ -0,0 +1,2 @@
+export { fateServer } from './fate/server.ts';
+export * from './fate/views.ts';

package/templates/fate/cloudflare/server/src/user/SessionUser.tsx

@@ -0,0 +1,17 @@
+import type { UserRow } from '../../db/schema.ts';
+
+export type SessionUser = Pick<UserRow, 'role' | 'id' | 'username'>;
+
+export function toSessionUser({
+  email,
+  id,
+  role,
+  username,
+}: Readonly<{
+  email: string | null | undefined;
+  id: string;
+  role?: string | null | undefined;
+  username?: string | null | undefined;
+}>): SessionUser {
+  return { id, role: role || '', username: username || email || '' };
+}

package/templates/fate/cloudflare/server/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "target": "ES2022",
+    "types": ["vite/client"]
+  },
+  "include": ["db/**/*.ts", "src/**/*.ts", "src/**/*.tsx"]
+}

package/templates/fate/cloudflare/server/wrangler.jsonc

@@ -0,0 +1,29 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "fate-cloudflare",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-06-05",
+  "compatibility_flags": ["nodejs_compat"],
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "fate-cloudflare",
+      "database_id": "00000000-0000-0000-0000-000000000000",
+      "migrations_dir": "db/migrations",
+    },
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "FATE_LIVE",
+        "class_name": "FateLiveDurableObject",
+      },
+    ],
+  },
+  "migrations": [
+    {
+      "tag": "fate-live-v1",
+      "new_sqlite_classes": ["FateLiveDurableObject"],
+    },
+  ],
+}

package/templates/fate/cloudflare/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2017",
+    "types": ["vite/client"]
+  },
+  "exclude": ["**/.void/**/*.ts", "node_modules"],
+  "include": ["**/.fate/*.ts", "**/*.ts", "**/*.tsx"],
+  "ts-node": {
+    "transpileOnly": true,
+    "transpiler": "ts-node/transpilers/swc",
+    "files": true,
+    "compilerOptions": {
+      "module": "esnext",
+      "isolatedModules": false
+    }
+  }
+}

package/templates/fate/cloudflare/vite.config.ts

@@ -0,0 +1,72 @@
+import { join } from 'node:path';
+import nkzw from '@nkzw/oxlint-config';
+import dotenv from 'dotenv';
+import { defineConfig } from 'vite-plus';
+
+const root = process.cwd();
+
+dotenv.config({
+  path: join(root, './server', '.env'),
+  quiet: true,
+});
+
+export default defineConfig({
+  fmt: {
+    experimentalSortImports: {
+      newlinesBetween: false,
+    },
+    experimentalSortPackageJson: {
+      sortScripts: true,
+    },
+    experimentalTailwindcss: {
+      stylesheet: 'client/src/App.css',
+    },
+    ignorePatterns: [
+      'coverage/',
+      'dist/',
+      '.fate/',
+      'client/dist/',
+      'client/src/translations/',
+      'server/dist/',
+      'server/.wrangler/',
+      'pnpm-lock.yaml',
+    ],
+    singleQuote: true,
+  },
+  lint: {
+    extends: [nkzw],
+    ignorePatterns: [
+      'coverage',
+      'dist',
+      '.fate',
+      'client/dist',
+      'server/dist',
+      'server/.wrangler',
+      'server/db/migrations/meta/**',
+      'vite.config.ts.timestamp-*',
+      'client/vite.config.ts.timestamp-*',
+    ],
+    options: { typeAware: true, typeCheck: true },
+    overrides: [
+      {
+        files: ['server/src/index.ts', '**/__tests__/**'],
+        rules: {
+          'no-console': 'off',
+        },
+      },
+    ],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  run: {
+    tasks: {
+      'test:all': {
+        command: 'vp check && vp test',
+      },
+    },
+  },
+  staged: {
+    '*': 'vp check --fix',
+  },
+});

package/templates/fate/drizzle/README.md

@@ -1,16 +1,10 @@
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="/public/fate-logo-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="/public/fate-logo.svg">
-    <img alt="Logo" src="/public/fate-logo.svg" width="50%">
-  </picture>
-</p>
+# _fate_
 
 **_fate_** is a modern data client for React inspired by [Relay](https://relay.dev/) and [GraphQL](https://graphql.org/). It combines view composition, normalized caching, data masking, Async React features, and type-safe data fetching.
 
 Check out [fate.technology](https://fate.technology) for documentation, examples, and guides.
 
-# _fate_ Quick Start Template
+## Quick Start Template
 
 Create a new fate app with Vite+:
 

package/templates/fate/drizzle/client/pages/layout.tsx

@@ -37,7 +37,7 @@ const LocaleContext = createLocaleContext({
 });
 
 export default function Layout({ children }: { children: ReactNode }) {
-  const { data: session, isPending } = AuthClient.useSession();
+  const { data: session } = AuthClient.useSession();
   const userId = session?.user.id;
 
   const fate = useMemo(
@@ -72,7 +72,7 @@ export default function Layout({ children }: { children: ReactNode }) {
       <div className="min-h-screen bg-background text-foreground">
         <div className="min-h-screen bg-[radial-gradient(circle_at_20%_20%,rgba(59,130,246,0.08),transparent_35%),radial-gradient(circle_at_80%_0,rgba(99,102,241,0.08),transparent_28%)]">
           <Header />
-          {isPending ? (
+          {session ? (
             <Thinking />
           ) : (
             <FateClient client={fate} key={userId}>

package/templates/fate/drizzle/client/src/ui/PostCard.tsx

@@ -4,6 +4,7 @@ import { cx } from 'class-variance-authority';
 import { fbs } from 'fbtee';
 import {
   KeyboardEvent,
+  Suspense,
   startTransition,
   useActionState,
   useCallback,
@@ -11,7 +12,16 @@ import {
   useState,
 } from 'react';
 import { ErrorBoundary } from 'react-error-boundary';
-import { useFateClient, useLiveListView, useLiveView, useView, view, ViewRef } from 'react-fate';
+import {
+  defer,
+  type Deferred,
+  useLiveListView,
+  useFateClient,
+  useLiveView,
+  useView,
+  view,
+  ViewRef,
+} from 'react-fate';
 import { Button } from '../ui/Button.tsx';
 import Card from '../ui/Card.tsx';
 import AuthClient from '../user/AuthClient.tsx';
@@ -33,13 +43,36 @@ const CommentConnectionView = {
 export const PostView = view<Post>()({
   author: UserView,
   commentCount: true,
-  comments: CommentConnectionView,
+  comments: defer(CommentConnectionView),
   content: true,
   id: true,
   likes: true,
   title: true,
 });
 
+const PostComments = ({
+  comments,
+  post,
+}: {
+  comments: Deferred<{ items: ReadonlyArray<{ node: ViewRef<'Comment'> }> }>;
+  post: { commentCount: number; id: string; title: string };
+}) => {
+  const [items, loadNext] = useLiveListView(CommentConnectionView, comments);
+
+  return items.length > 0 ? (
+    <VStack gap={12}>
+      {items.map(({ node }) => (
+        <CommentCard comment={node} key={node.id} post={post} />
+      ))}
+      {loadNext ? (
+        <Button onClick={loadNext} variant="ghost">
+          <fbt desc="Load more comments button">Load more comments</fbt>
+        </Button>
+      ) : null}
+    </VStack>
+  ) : null;
+};
+
 const CommentInput = ({
   error,
   post,
@@ -128,7 +161,6 @@ export function PostCard({ detail, post: postRef }: { detail?: boolean; post: Vi
   const fate = useFateClient();
   const post = useLiveView(PostView, postRef);
   const author = useView(UserView, post.author);
-  const [comments, loadNext] = useLiveListView(CommentConnectionView, post.comments);
 
   const [likeResult, likeAction, likeIsPending] = useActionState(fate.actions.post.like, null);
 
@@ -262,18 +294,9 @@ export function PostCard({ detail, post: postRef }: { detail?: boolean; post: Vi
               </fbt:plural>
             </fbt>
           </h4>
-          {comments.length > 0 ? (
-            <VStack gap={12}>
-              {comments.map(({ node }) => (
-                <CommentCard comment={node} key={node.id} post={post} />
-              ))}
-              {loadNext ? (
-                <Button onClick={loadNext} variant="ghost">
-                  <fbt desc="Load more comments button">Load more comments</fbt>
-                </Button>
-              ) : null}
-            </VStack>
-          ) : null}
+          <Suspense fallback={null}>
+            <PostComments comments={post.comments} post={post} />
+          </Suspense>
           <ErrorBoundary fallbackRender={({ error }) => <CommentInput error={error} post={post} />}>
             <CommentInput post={post} />
           </ErrorBoundary>

package/templates/fate/drizzle/pnpm-workspace.yaml

@@ -11,9 +11,14 @@ allowBuilds:
   workerd: true
 
 catalog:
-  vite: npm:@voidzero-dev/vite-plus-core@^0.1.20
-  vite-plus: ^0.1.20
-  vitest: npm:@voidzero-dev/vite-plus-test@^0.1.20
+  vite: npm:@voidzero-dev/vite-plus-core@^0.1.23
+  vite-plus: ^0.1.23
+  vitest: npm:@voidzero-dev/vite-plus-test@^0.1.23
+
+minimumReleaseAgeExclude:
+  - '@voidzero-dev/vite-plus-core'
+  - '@voidzero-dev/vite-plus-test'
+  - vite-plus
 
 onlyBuiltDependencies:
   - '@swc/core'
@@ -24,6 +29,7 @@ onlyBuiltDependencies:
   - unrs-resolver
 
 overrides:
+  kysely: 0.28.17
   vite: 'catalog:'
   vitest: 'catalog:'
 

package/templates/fate/drizzle/server/vite.config.ts

@@ -3,6 +3,6 @@ import { defineConfig } from 'vite-plus';
 export default defineConfig({
   pack: {
     entry: ['./src/app.tsx'],
-    outputOptions: { codeSplitting: false, file: 'dist/index.js' },
+    outputOptions: { codeSplitting: false, entryFileNames: 'index.js' },
   },
 });

package/templates/fate/graphql/.github/workflows/push.yml

@@ -0,0 +1,27 @@
+name: test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: true
+          run-install: true
+      - run: |
+          vp run dev:setup
+          vp run test:all
+          vp run build

package/templates/fate/graphql/.vite-hooks/pre-commit

@@ -0,0 +1 @@
+vp staged

package/templates/fate/graphql/.vscode/extensions.json

@@ -0,0 +1,12 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "oxc.oxc-vscode",
+    "styled-components.vscode-styled-components",
+    "sysoev.vscode-open-in-github",
+    "tailwindcss.intellisense",
+    "TypeScriptTeam.native-preview",
+    "usernamehw.errorlens",
+    "wix.vscode-import-cost"
+  ]
+}

package/templates/fate/graphql/.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "editor.formatOnSave": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "typescript.preferences.importModuleSpecifierEnding": "js",
+  "typescript.reportStyleChecksAsWarnings": false,
+  "typescript.updateImportsOnFileMove.enabled": "always",
+  "typescript.preferences.autoImportFileExcludePatterns": ["**/node_modules/vitest"],
+  "typescript.experimental.useTsgo": true
+}

package/templates/fate/graphql/AGENTS.md

@@ -0,0 +1,55 @@
+# Using _fate_ for React applications
+
+This guidance is for agents working in projects bootstrapped from the fate template. It focuses on the client-side patterns for fate's view composition and action execution.
+
+## Core Workflow
+
+- **Define views with explicit selections:** Define reusable view objects with `view<T>()({...})`, compose them via spreads, and resolve them with `useView`.
+- **Resolve data via references:** Avoid passing raw fetched objects; instead pass `ViewRef`s to downstream components to keep selections scoped and cache-aware. Then call `const result = useView(viewDefinition, ref)` to read only the selected fields while subscribing to cache updates. Name the prop after the result data, and rename it using destructuring in the function arguments: `const PostComponent = ({ post: postRef }: { post: ViewRef<'Post'>}) => { const post = useView(PostView, postRef); ... }`.
+- **Request data at screen roots:** Use `useRequest` to compose all views required for a route or screen into a single typed request; wrap roots in `Suspense` and an error boundary since requests may suspend or throw.
+- **Compose reusable views:** Extract nested selections into their own views (e.g., `UserView`) and compose them inside parent views (`author: UserView`) to avoid duplication and overfetching. This keeps selections DRY and ensures view updates propagate consistently when the cache changes.
+
+## Actions & Mutations
+
+- **Prefer `fate.actions` with `useActionState`:** Trigger mutations through React Actions to integrate with Suspense/`useTransition`, receiving `[result, action, isPending]`. Call actions via the relevant data inputs, for example `action({input: { id: post.id }})`.
+- **Optimistic updates by default:** Pass `optimistic` payloads to immediately update the normalized cache; only views selecting the changed fields re-render and failures roll back automatically. Optimistic payloads should match the expected server data changes of the associated object.
+- **Select extra fields when side effects matter:** When a mutation affects related entities (e.g., comment count on a post), pass a `view` to the action to fetch the needed fields in the same round-trip and keep the cache coherent for all dependent views.
+- **Imperative escape hatch:** Use `fate.mutations` when you must fire mutations outside React components or without waiting on prior actions; handle loading/error states yourself.
+- **Handle deletions and resets explicitly:** Use the `delete: true` flag to evict records from the cache, and send the `'reset'` token to clear stale action errors without re-running the mutation.
+- **Error handling model:** Treat expected errors (e.g., 404) at the call site via the action result; unexpected errors bubble to the nearest React error boundary.
+
+## Common Pitfalls
+
+- **Use ViewRefs:** Pass references instead of raw data. Keep components focused on views and `ViewRef`s to let fate manage data masking and updates.
+- **Co-locate data needs:** Keep view definitions near their components and compose them upward to the request root for predictable fetching.
+- **Use Suspense:** Wrap pages in `Suspense`/`ErrorBoundary` instead of ad-hoc loading/error flags; fate aligns with Async React by design.
+- **Do not duplicate types:** Keep generated GraphQL/Fate types and views imported from the server package. Avoid redefining entity shapes on the client. This ensures view selections stay type-safe end-to-end.
+- **`useRequest` only at the root:** When adding routes or layouts, create a dedicated `useRequest` call per screen root that pulls together all child views; do not scatter `useRequest` across leaf components unless it's necessary to issue requests due to user input.
+- **React Actions:** Prefer React Action-friendly UI primitives (buttons/forms that accept an `action` prop). If unavailable, wrap action calls with `startTransition` in `onClick` handlers.
+- **fate client support** fate's local client support files are maintained by the Vite/fate tooling. Do not manually edit `.fate` files; make the proper schema changes on the server and run `pnpm fate:generate` when working outside Vite dev.
+- **Library Versions:** This repository uses the most recent releases of React, fate, Vite, GraphQL, and more. You might not know about the new releases yet, please don't get confused. The versions you see are real, and there are no feature or version mismatches. You can search the internet for more information about them.
+
+Full documentation can be found on the filesystem at `./client/node_modules/react-fate/README.md` or online at [fate.technology](https://fate.technology/).
+
+## Review Checklist for Agents
+
+- [ ] Every component that reads server data does so through `useView` and receives a `ViewRef` prop.
+- [ ] Root components gather data with a single `useRequest` call.
+- [ ] Mutations are wired through `useActionState` with optimistic updates and necessary `view` selections; imperative `fate.mutations` are justified when used.
+- [ ] Shared selections live in reusable views using regular JavaScript object spreads rather than duplicated field lists.
+
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+
+<!--VITE PLUS END-->

package/templates/fate/graphql/README.md

@@ -0,0 +1,121 @@
+# _fate_
+
+**_fate_** is a modern data client for React inspired by [Relay](https://relay.dev/) and [GraphQL](https://graphql.org/). It combines view composition, normalized caching, data masking, Async React features, and type-safe data fetching.
+
+Check out [fate.technology](https://fate.technology) for documentation, examples, and guides.
+
+## Quick Start Template
+
+Create a new fate app with Vite+:
+
+```bash
+vp create fate my-app --template graphql
+```
+
+## Getting Started with _fate_
+
+Read the [Getting Started Guide](https://fate.technology/guide/core-concepts) to learn how to use _fate_ in your React applications.
+
+## Technologies
+
+This default template combines the Nakazawa Tech's [Web App Template](https://github.com/nkzw-tech/web-app-template) and [Server Template](https://github.com/nkzw-tech/server-template) into a monorepo, with unified tooling and _fate_ as the data client. It currently uses GraphQL with Pothos, Relay-style connections, and Prisma.
+
+_This template lives on the edge._ It's a turbocharged starting point on top of an already optimized stack. It uses TypeScript Go, Vite+, and ships with sensible defaults to unlock an incredibly fast development experience. It follows the principles laid out in [Building Scalable Applications](https://www.youtube.com/watch?v=rxPTEko8J7c&t=36s).
+
+Next to [_fate_](https://fate.technology), it comes with the following technologies:
+
+### Client Technologies
+
+- [Vite 8](https://vitejs.dev/)
+- [React](https://reactjs.org/) with [React Compiler](https://react.dev/learn/react-compiler) enabled
+- [Tailwind](https://tailwindcss.com/)
+- [fbtee](https://github.com/nkzw-tech/fbtee) for i18n
+- [Better Auth](https://www.better-auth.com/) for authentication
+- [Void Pages Router](https://void.cloud/docs)
+- [TypeScript](https://www.typescriptlang.org)
+- [pnpm](https://pnpm.io/)
+
+### Server Technologies
+
+- [Prisma](https://www.prisma.io/) as the ORM, with the new ESM multi-file generated client.
+- [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) and [Pothos](https://pothos-graphql.dev/) for the GraphQL API.
+- [graphql-sse](https://github.com/enisdenjo/graphql-sse) for live updates.
+- [Hono](https://hono.dev/)
+- [Better Auth](https://better-auth.com/) for Authentication.
+
+### Folder Structure
+
+- `client/` - The React client application using _fate_.
+- `server/` - The fate server using GraphQL with Pothos and Prisma.
+
+## Initial Setup
+
+You'll need Node.js 24+ and [Vite+](https://viteplus.dev/guide/).
+
+Install dependencies:
+
+```bash
+vp install
+```
+
+Review `server/.env`, which is copied from `server/.env.example` when the app is created. The default local values expect:
+
+- Postgres at `postgresql://fate:echo@localhost:5432/fate`.
+- The server at `http://localhost:9000`.
+- The client at `http://localhost:5173`.
+
+Start Postgres with Docker:
+
+```bash
+docker-compose up -d
+```
+
+Alternatively, create the database manually:
+
+```SQL
+CREATE ROLE fate WITH LOGIN PASSWORD 'echo';
+CREATE DATABASE fate;
+ALTER DATABASE fate OWNER TO fate;
+```
+
+For local development, push the Prisma schema and seed the database:
+
+```bash
+vp run prisma db push
+vp run prisma db seed
+```
+
+If you prefer migration files, use Prisma's migration workflow instead:
+
+```bash
+vp run prisma migrate dev --name init
+vp run prisma db seed
+```
+
+Then generate local files:
+
+```bash
+vp run dev:setup
+```
+
+Start the app:
+
+```bash
+vp run dev
+```
+
+The client runs at `http://localhost:5173` and the server runs at `http://localhost:9000`. GraphQL requests go to `/graphql` and live updates use `/graphql/stream`.
+
+## Development
+
+Common commands from the project root:
+
+- `vp run dev` starts the client and server together.
+- `vp run dev:client` starts only the client.
+- `vp run dev:server` starts only the server.
+- `vp run dev:setup` generates the Prisma client, Pothos schema import map, fbtee setup, and fate client support.
+- `vp run fate:generate` refreshes fate client support after changing server views, roots, or routers.
+- `vp run prisma` runs Prisma CLI commands in the server package.
+- `vp check --fix` formats, lints, and type-checks the workspace.
+- `vp test` runs the test suite.
+- `vp run build` builds the client and server.