create-fate 1.0.4 → 1.3.1

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

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

package/templates/fate/cloudflare/.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/cloudflare/.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/cloudflare/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 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, 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/cloudflare/README.md

@@ -0,0 +1,126 @@
+# _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, live updates, 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 cloudflare
+```
+
+## Technologies
+
+This template is a client plus Cloudflare Worker server app. It uses the Cloudflare fate transport, D1 with Drizzle, Better Auth, and Cloudflare Durable Objects for SSE-backed live updates.
+
+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
+
+- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
+- [Cloudflare D1](https://developers.cloudflare.com/d1/) with [Drizzle](https://orm.drizzle.team/)
+- Cloudflare Durable Objects for fate live SSE fanout
+- [Better Auth](https://better-auth.com/) for authentication
+
+### Folder Structure
+
+- `client/` - The React client application using _fate_.
+- `server/` - The Cloudflare Worker fate server using D1 with Drizzle.
+- `server/db/migrations/` - D1 migrations, including the seed data used by the demo UI.
+
+## Initial Setup
+
+You'll need Node.js 24+, [Vite+](https://viteplus.dev/guide/), and a Cloudflare account if you plan to deploy.
+
+Install dependencies:
+
+```bash
+vp install
+```
+
+Review `server/.env`, which is copied from `server/.env.example` when the app is created. The default local value points the client at Wrangler's local Worker:
+
+```bash
+VITE_SERVER_URL=http://localhost:8787
+```
+
+Set up the local D1 database, seed data, translations, and fate client support:
+
+```bash
+vp run dev:setup
+```
+
+Start the app:
+
+```bash
+vp run dev
+```
+
+The client runs at `http://localhost:6001` and the Worker runs at `http://localhost:8787`. Cloudflare fate requests go to `/fate`; live updates use the SSE endpoint at `/fate-live`.
+
+The seeded demo login is:
+
+- `alex@example.com`
+- `password-alex`
+
+## Development
+
+Common commands from the project root:
+
+- `vp run dev` starts the client and Worker together.
+- `vp run dev:client` starts only the client.
+- `vp run dev:server` starts only the Worker.
+- `vp run dev:setup` applies local D1 migrations, runs fbtee setup, and prepares fate client support.
+- `vp run fate:generate` refreshes fate client support after changing server views, roots, or mutations.
+- `vp check --fix` formats, lints, and type-checks the workspace.
+- `vp test` runs the test suite.
+- `vp run build` type-checks the Worker and builds the client.
+
+## Deploying to Cloudflare
+
+Create a D1 database and copy the generated `database_id` into `server/wrangler.jsonc`:
+
+```bash
+cd server
+pnpm exec wrangler d1 create fate-cloudflare
+```
+
+Set a production Better Auth secret:
+
+```bash
+pnpm exec wrangler secret put BETTER_AUTH_SECRET
+```
+
+Apply the migrations to the remote D1 database:
+
+```bash
+pnpm run db:migrate:remote
+```
+
+Deploy the Worker:
+
+```bash
+pnpm run deploy
+```
+
+To test the local client against the deployed Worker, run this from the project root:
+
+```bash
+VITE_SERVER_URL="https://<your-worker>.<your-subdomain>.workers.dev" pnpm run dev:client
+```
+
+If you deploy the client to a hosted origin, add that origin to `server/src/lib/origins.ts`.

package/templates/fate/cloudflare/_gitignore

@@ -0,0 +1,20 @@
+.fate/
+**/.fate/
+.void/
+**/.void/
+.eslintcache
+.pnpm-debug.log
+**/node_modules/
+/node_modules/
+client/.enum_manifest.json
+client/dist/
+client/source_strings.json
+client/src/translations/
+coverage/
+dist/
+server/.env
+server/.prod.env
+server/.wrangler/
+server/dist/
+tsconfig.tsbuildinfo
+vite.config.ts.timestamp-*

package/templates/fate/cloudflare/client/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@app/client",
+  "version": "0.0.1",
+  "private": true,
+  "author": "Christoph Nakazawa <christoph.pojer@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/nkzw-tech/fate.git"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "vp build",
+    "dev": "vp dev",
+    "dev:setup": "vp run fbtee:all",
+    "fate:generate": "vp exec fate generate",
+    "fbtee:all": "vpx fbtee collect && vpx fbtee translate"
+  },
+  "dependencies": {
+    "@app/server": "workspace:*",
+    "@nkzw/core": "^1.3.1",
+    "@nkzw/define-env": "^1.1.0",
+    "@nkzw/stack": "^2.3.2",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@void/react": "^0.7.13",
+    "better-auth": "^1.6.9",
+    "cf-fate": "latest",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "fbtee": "^1.7.4",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-error-boundary": "^6.1.1",
+    "react-fate": "latest",
+    "tailwind-merge": "^3.5.0",
+    "void": "^0.7.13"
+  },
+  "devDependencies": {
+    "@nkzw/babel-preset-fbtee": "^1.7.4",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tailwindcss": "^4.2.4",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "browserslist": [
+    ">0.2%",
+    "not dead",
+    "not op_mini all"
+  ]
+}

package/templates/fate/cloudflare/client/pages/index.tsx

@@ -0,0 +1,96 @@
+import Stack, { VStack } from '@nkzw/stack';
+import { ConnectionRef, useListView, useRequest } from 'react-fate';
+import cx from '../src/lib/cx.tsx';
+import { Button } from '../src/ui/Button.tsx';
+import Card from '../src/ui/Card.tsx';
+import H2 from '../src/ui/H2.tsx';
+import Link from '../src/ui/Link.tsx';
+import { PostCard, PostView } from '../src/ui/PostCard.tsx';
+import Section from '../src/ui/Section.tsx';
+import UserCard, { UserView } from '../src/ui/UserCard.tsx';
+
+const PostConnectionView = {
+  args: { first: 3 },
+  items: {
+    node: PostView,
+  },
+  pagination: {
+    hasNext: true,
+  },
+};
+
+const PostFeed = ({ posts: postsRef }: { posts: ConnectionRef<'Post'> }) => {
+  const [posts, loadNext] = useListView(PostConnectionView, postsRef);
+
+  return posts.length ? (
+    <VStack gap={16}>
+      <H2 className="pl-5">
+        <fbt desc="Latest posts header">Latest posts</fbt>
+      </H2>
+      <VStack gap={32}>
+        {posts.map(({ node }) => (
+          <PostCard key={node.id} post={node} />
+        ))}
+        {loadNext ? (
+          <Stack center>
+            <Button onClick={loadNext} variant="ghost">
+              <fbt desc="Load more posts button">Load more posts</fbt>
+            </Button>
+          </Stack>
+        ) : null}
+      </VStack>
+    </VStack>
+  ) : null;
+};
+
+export default function HomePage() {
+  const { posts, viewer } = useRequest({
+    posts: { list: PostConnectionView },
+    viewer: { view: UserView },
+  });
+
+  return (
+    <Section gap={32}>
+      <div
+        className={cx('grid gap-8 lg:items-stretch', viewer?.id ? 'lg:grid-cols-[1.6fr_1fr]' : '')}
+      >
+        <Card className="border border-white/20 bg-linear-to-r from-blue-500 to-sky-500 text-white dark:from-blue-600 dark:to-sky-600">
+          <Stack alignCenter gap={12} wrap>
+            <span className="squircle bg-white/20 px-2 py-1 text-xs font-semibold tracking-widest uppercase">
+              <span className="lowercase italic">fate</span> demo
+            </span>
+          </Stack>
+          <div className="space-y-3">
+            <h1 className="text-3xl leading-tight font-semibold text-balance lg:text-4xl">
+              <fbt desc="Description of fate">
+                fate is a modern data client for React inspired by Relay and GraphQL.
+              </fbt>
+            </h1>
+            <p className="text-sm text-white/80 lg:text-base">
+              <fbt desc="Tagline for fate">
+                fate combines view composition, normalized caching, data masking, Async React
+                features, and type-safe data fetching.
+              </fbt>
+            </p>
+          </div>
+          <Stack alignCenter gap={12} wrap>
+            {!viewer?.id && (
+              <>
+                <Button asChild size="sm" variant="secondary">
+                  <Link className="squircle px-4 py-2 text-sm font-semibold" to="/login">
+                    <fbt desc="Login button">Login</fbt>
+                  </Link>
+                </Button>
+                <span className="text-sm text-white/80">
+                  <fbt desc="Login button label">Sign in to post comments.</fbt>
+                </span>
+              </>
+            )}
+          </Stack>
+        </Card>
+        {viewer?.id && <UserCard user={viewer} />}
+      </div>
+      <PostFeed posts={posts} />
+    </Section>
+  );
+}

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

@@ -0,0 +1,82 @@
+/// <reference types="fbtee/ReactTypes.d.ts" />
+
+import '../src/App.css';
+import Stack from '@nkzw/stack';
+import { createLocaleContext } from 'fbtee';
+import { ReactNode, Suspense, useMemo } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+import { FateClient } from 'react-fate';
+import { createFateClient } from 'react-fate/client';
+import AvailableLanguages from '../src/lib/AvailableLanguages.tsx';
+import env from '../src/lib/env.tsx';
+import Card from '../src/ui/Card.tsx';
+import Error from '../src/ui/Error.tsx';
+import Header from '../src/ui/Header.tsx';
+import Section from '../src/ui/Section.tsx';
+import AuthClient from '../src/user/AuthClient.tsx';
+
+const Thinking = () => (
+  <Section>
+    <Stack center className="animate-pulse text-gray-500 italic" verticalPadding={48}>
+      <fbt desc="Text for thinking/loading screen">Thinking...</fbt>
+    </Stack>
+  </Section>
+);
+
+const LocaleContext = createLocaleContext({
+  availableLanguages: AvailableLanguages,
+  clientLocales: [navigator.language, ...navigator.languages],
+  loadLocale: async (locale: string) => {
+    if (locale !== 'en_US' && AvailableLanguages.has(locale)) {
+      return (await import(`../src/translations/${locale}.json`)).default[locale];
+    }
+
+    return {};
+  },
+});
+
+export default function Layout({ children }: { children: ReactNode }) {
+  const { data: session } = AuthClient.useSession();
+  const userId = session?.user.id;
+
+  const fate = useMemo(
+    () =>
+      createFateClient({
+        fetch: (input, init) =>
+          fetch(input, {
+            ...init,
+            credentials: userId ? 'include' : undefined,
+          }),
+        liveUrl: `${env('SERVER_URL')}/fate-live`,
+        url: `${env('SERVER_URL')}/fate`,
+      }),
+    [userId],
+  );
+
+  return (
+    <LocaleContext>
+      <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 />
+          {session ? (
+            <Thinking />
+          ) : (
+            <FateClient client={fate} key={userId}>
+              <ErrorBoundary
+                fallbackRender={({ error }) => (
+                  <Section>
+                    <Card>
+                      <Error error={error} />
+                    </Card>
+                  </Section>
+                )}
+              >
+                <Suspense fallback={<Thinking />}>{children}</Suspense>
+              </ErrorBoundary>
+            </FateClient>
+          )}
+        </div>
+      </div>
+    </LocaleContext>
+  );
+}

package/templates/fate/cloudflare/client/pages/login.tsx

@@ -0,0 +1,107 @@
+import Stack, { VStack } from '@nkzw/stack';
+import { useRouter } from '@void/react';
+import { fbs } from 'fbtee';
+import { ExternalLinkIcon } from 'lucide-react';
+import { useActionState, useEffect, useState } from 'react';
+import { AsyncButton } from '../src/ui/Button.tsx';
+import Card from '../src/ui/Card.tsx';
+import H2 from '../src/ui/H2.tsx';
+import Input from '../src/ui/Input.tsx';
+import Section from '../src/ui/Section.tsx';
+import AuthClient from '../src/user/AuthClient.tsx';
+
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const router = useRouter();
+  const { data: session } = AuthClient.useSession();
+
+  const [, signInAction] = useActionState(async () => {
+    await AuthClient.signIn.email(
+      {
+        email,
+        password,
+      },
+      {
+        onError: () => {},
+        onRequest: () => {},
+        onSuccess: () => {
+          router.flushAll();
+          void router.visit('/', { replace: true });
+        },
+      },
+    );
+
+    return null;
+  }, null);
+
+  useEffect(() => {
+    if (session) {
+      router.flushAll();
+      void router.visit('/', { replace: true });
+    }
+  }, [router, session]);
+
+  if (session) {
+    return null;
+  }
+
+  return (
+    <Section>
+      <VStack center gap={16}>
+        <H2 className="pl-5">
+          <fbt desc="Sign In headline">Sign In</fbt>
+        </H2>
+        <Stack gap={32} wrap>
+          <Card className="w-84">
+            <Stack gap vertical>
+              <VStack action={signInAction} as="form" gap={12}>
+                <Input
+                  className="w-48"
+                  name="email"
+                  onChange={(e) => setEmail(e.target.value)}
+                  placeholder={fbs('email', 'Email placeholder')}
+                  type="email"
+                  value={email}
+                />
+                <Input
+                  className="w-48"
+                  name="password"
+                  onChange={(e) => setPassword(e.target.value)}
+                  placeholder={fbs('password', 'Password placeholder')}
+                  type="password"
+                  value={password}
+                />
+                <div>
+                  <AsyncButton type="submit" variant="outline">
+                    <fbt desc="Sign in button">Sign In</fbt>
+                  </AsyncButton>
+                </div>
+              </VStack>
+            </Stack>
+          </Card>
+          <Card className="w-84">
+            <p>
+              <fbt desc="Login details">
+                Try one of the
+                <Stack
+                  alignCenter
+                  as="a"
+                  className="inline-flex! px-1 underline hover:no-underline"
+                  gap={4}
+                  href="https://github.com/nkzw-tech/fate/blob/main/packages/create-fate/templates/fate/cloudflare/server/db/migrations/20260508120500_seed_cloudflare_demo.sql#L1"
+                  rel="noreferrer"
+                  target="_blank"
+                >
+                  Example Accounts
+                  <ExternalLinkIcon className="h-4 w-4" />
+                </Stack>{' '}
+                in the seed data.
+              </fbt>
+            </p>
+          </Card>
+        </Stack>
+      </VStack>
+    </Section>
+  );
+}

package/templates/fate/cloudflare/client/pages/post/[id].tsx

@@ -0,0 +1,22 @@
+import { useParams } from '@void/react';
+import { useRequest } from 'react-fate';
+import { PostCard, PostView } from '../../src/ui/PostCard.tsx';
+import Section from '../../src/ui/Section.tsx';
+
+export default function PostPage() {
+  const { id } = useParams<{ id: string }>();
+
+  if (!id) {
+    throw new Error('fate: Post ID is required.');
+  }
+
+  const { post } = useRequest({
+    post: { id, view: PostView },
+  });
+
+  return (
+    <Section>
+      <PostCard detail post={post} />
+    </Section>
+  );
+}