create-fate 0.0.0 → 1.0.0

package/templates/fate/drizzle/server/src/trpc/routers/post.ts

@@ -0,0 +1,99 @@
+import { connectionArgs } from '@nkzw/fate/server';
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { likePostRecord, unlikePostRecord } from '../../drizzle/queries.ts';
+import { fate, live, procedure, router } from '../init.ts';
+import { Post, postDataView } from '../views.ts';
+
+export const postRouter = router({
+  ...fate.procedures({
+    view: postDataView,
+  }),
+  like: procedure
+    .input(
+      z.object({
+        args: connectionArgs,
+        error: z.enum(['boundary', 'callSite']).optional(),
+        id: z.string().min(1, 'Post id is required.'),
+        select: z.array(z.string()),
+        slow: z.boolean().optional(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      if (input.slow) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+      }
+
+      if (input.error === 'boundary') {
+        throw new TRPCError({
+          code: 'INTERNAL_SERVER_ERROR',
+          message: 'Simulated error.',
+        });
+      } else if (input.error === 'callSite') {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        throw new TRPCError({
+          code: 'PAYMENT_REQUIRED',
+          message: 'Gotta pay up.',
+        });
+      }
+
+      const updated = await likePostRecord(input.id);
+      if (!updated) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Post not found.',
+        });
+      }
+
+      const post = await fate.resolveById({
+        ctx,
+        id: input.id,
+        input,
+        view: postDataView,
+      });
+      if (!post) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Post not found.',
+        });
+      }
+
+      live.update('Post', input.id, { changed: ['likes'] });
+
+      return post as Post;
+    }),
+  unlike: procedure
+    .input(
+      z.object({
+        args: connectionArgs,
+        id: z.string().min(1, 'Post id is required.'),
+        select: z.array(z.string()),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const updated = await unlikePostRecord(input.id);
+      if (!updated) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Post not found',
+        });
+      }
+
+      const post = await fate.resolveById({
+        ctx,
+        id: input.id,
+        input,
+        view: postDataView,
+      });
+      if (!post) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Post not found',
+        });
+      }
+
+      live.update('Post', input.id, { changed: ['likes'] });
+
+      return post as Post;
+    }),
+});

package/templates/fate/drizzle/server/src/trpc/routers/user.ts

@@ -0,0 +1,68 @@
+import { connectionArgs } from '@nkzw/fate/server';
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { auth } from '../../lib/auth.ts';
+import { fate, procedure, router } from '../init.ts';
+import { userDataView } from '../views.ts';
+
+export const userRouter = router({
+  update: procedure
+    .input(
+      z.object({
+        args: connectionArgs,
+        name: z
+          .string()
+          .trim()
+          .min(2, 'Name must be at least 2 characters.')
+          .max(50, 'Name must be at most 32 characters.'),
+        select: z.array(z.string()),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      if (!ctx.sessionUser) {
+        throw new TRPCError({
+          code: 'UNAUTHORIZED',
+          message: 'You must be logged in to update your name.',
+        });
+      }
+
+      await auth.api.updateUser({
+        body: { name: input.name },
+        headers: ctx.headers,
+      });
+
+      const result = await fate.resolveById({
+        ctx,
+        id: ctx.sessionUser.id,
+        input,
+        view: userDataView,
+      });
+      if (!result) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'User not found.',
+        });
+      }
+
+      return result;
+    }),
+  viewer: procedure
+    .input(
+      z.object({
+        select: z.array(z.string()),
+      }),
+    )
+    .query(async ({ ctx, input }) => {
+      if (!ctx.sessionUser) {
+        return null;
+      }
+
+      const result = await fate.resolveById({
+        ctx,
+        id: ctx.sessionUser.id,
+        input,
+        view: userDataView,
+      });
+      return result;
+    }),
+});

package/templates/fate/drizzle/server/src/trpc/views.ts

@@ -0,0 +1,75 @@
+import { computed, count, dataView, list, type Entity } from '@nkzw/fate/server';
+import type { CommentRow, PostRow, UserRow } from '../drizzle/schema.ts';
+
+export type CommentItem = CommentRow & {
+  author?: UserRow | null;
+  post?: PostRow | null;
+};
+
+export type PostItem = PostRow & {
+  author?: UserRow | null;
+  comments?: Array<CommentItem>;
+};
+
+export const userDataView = dataView<UserRow>('User')({
+  id: true,
+  name: true,
+  username: true,
+});
+
+const basePost = {
+  author: userDataView,
+  commentCount: computed<PostItem, number>({
+    resolve: (_item, deps) => (deps.count as number) ?? 0,
+    select: {
+      count: count('comments'),
+    },
+  }),
+  content: true,
+  id: true,
+  likes: true,
+  title: true,
+} as const;
+
+export const postSummaryDataView = dataView<PostItem>('Post')({
+  ...basePost,
+});
+
+export const commentDataView = dataView<CommentItem>('Comment')({
+  author: userDataView,
+  content: true,
+  id: true,
+  post: postSummaryDataView,
+});
+
+export const postDataView = dataView<PostItem>('Post')({
+  ...basePost,
+  comments: list(commentDataView, { orderBy: { createdAt: 'asc', id: 'asc' } }),
+});
+
+export type User = Entity<typeof userDataView, 'User'>;
+export type Comment = Entity<
+  typeof commentDataView,
+  'Comment',
+  {
+    author: User;
+    post: Post;
+  }
+>;
+export type Post = Entity<
+  typeof postDataView,
+  'Post',
+  {
+    author: User;
+    comments: Array<Comment>;
+  }
+>;
+
+export const Root = {
+  commentSearch: {
+    procedure: 'search',
+    view: list(commentDataView, { orderBy: { createdAt: 'desc', id: 'desc' } }),
+  },
+  posts: list(postDataView, { orderBy: { createdAt: 'desc', id: 'desc' } }),
+  viewer: userDataView,
+};

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

@@ -0,0 +1,17 @@
+import type { UserRow } from '../drizzle/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/drizzle/server/vite.config.ts

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

package/templates/fate/drizzle/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/drizzle/vite.config.ts

@@ -0,0 +1,71 @@
+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/',
+      'pnpm-lock.yaml',
+    ],
+    singleQuote: true,
+  },
+  lint: {
+    extends: [nkzw],
+    ignorePatterns: [
+      'coverage',
+      'dist',
+      '.fate',
+      'client/dist',
+      'server/dist',
+      'server/src/drizzle/migrations/**',
+      'vite.config.ts.timestamp-*',
+      'client/vite.config.ts.timestamp-*',
+      'server/vite.config.ts.timestamp-*',
+    ],
+    options: { typeAware: true, typeCheck: true },
+    overrides: [
+      {
+        files: ['server/src/index.tsx', 'server/src/drizzle/seed.tsx', '**/__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/http/.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/http/.oxfmtrc.jsonc

@@ -0,0 +1,23 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "singleQuote": true,
+  "experimentalSortImports": {
+    "newlinesBetween": false,
+  },
+  "experimentalSortPackageJson": {
+    "sortScripts": true,
+  },
+  "experimentalTailwindcss": {
+    "stylesheet": "client/src/App.css",
+  },
+  "ignorePatterns": [
+    "client/dist/",
+    "client/index.html",
+    "client/src/fate.ts",
+    "client/src/translations/",
+    "coverage/",
+    "dist/",
+    "pnpm-lock.yaml",
+    "server/dist",
+  ],
+}

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

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

package/templates/fate/http/.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/http/.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/http/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.
+- **Generated Client** The fate client is generated via `pnpm fate:generate`. It should not be manually edited. Instead make the proper schema changes on the server and run `pnpm fate:generate`.
+- **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/http/README.md

@@ -0,0 +1,112 @@
+<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_** 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
+
+Create a new fate app with Vite+:
+
+```bash
+vp create fate my-app --template http
+```
+
+## 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 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 uses the native fate HTTP transport with Drizzle.
+
+_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
+
+- [Drizzle](https://orm.drizzle.team/) as the ORM.
+- Native fate HTTP transport for type-safe data fetching.
+- [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 native HTTP with Drizzle.
+
+## 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;
+```
+
+Then set up the schema, seed data, translations, and generated fate client:
+
+```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`. Native fate requests go to `/fate`; live updates use the SSE endpoint under `/fate/live`.
+
+## 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` pushes the Drizzle schema, seeds the database, runs fbtee setup, and regenerates the fate client.
+- `vp run fate:generate` regenerates `client/.fate/client.generated.ts` after changing server views, roots, or mutations.
+- `vp run drizzle` opens Drizzle Kit commands for 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.

package/templates/fate/http/_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/dist/
+server/src/prisma/prisma-client/
+tsconfig.tsbuildinfo
+vite.config.ts.timestamp-*