create-cfast 0.0.1 → 0.2.0

package/dist/index.js

@@ -62,6 +62,7 @@ function resolveFeatureDeps(features) {
   }
   if (resolved.auth) {
     resolved.db = true;
+    resolved.ui = true;
   }
   return resolved;
 }
@@ -413,7 +414,7 @@ ${appLine}
 function generateViteConfig(config) {
   const optimizeDeps = [];
   if (config.features.ui && config.uiLibrary === "joy") {
-    optimizeDeps.push(`"@cfast/ui/joy"`);
+    optimizeDeps.push(`"@cfast/joy"`);
   }
   if (config.features.ui) {
     optimizeDeps.push(`"@cfast/actions/client"`);
@@ -469,7 +470,7 @@ function generateRootTsx(config) {
     imports.push(
       `import { createUIPlugin, UIPluginProvider, ConfirmProvider } from "@cfast/ui";`
     );
-    imports.push(`import { ConfirmDialog } from "@cfast/ui/joy";`);
+    imports.push(`import { ConfirmDialog } from "@cfast/joy";`);
     pluginSetup = `
 const plugin = createUIPlugin({
   components: { confirmDialog: ConfirmDialog },
@@ -594,6 +595,42 @@ function generateDevVars(config) {
   return lines.join("\n") + "\n";
 }
 
+// src/generators/auth-setup.ts
+function generateAuthSetup(config) {
+  const imports = [
+    `import { createAuth } from "@cfast/auth";`,
+    `import * as schema from "./db/schema";`,
+    `import { permissions } from "./permissions";`,
+    `import { env } from "./env";`
+  ];
+  let sendMagicLinkBody;
+  if (config.features.email) {
+    imports.push(`import { email as emailClient } from "~/email.server";`);
+    imports.push(`import { MagicLinkEmail } from "~/email/templates/magic-link";`);
+    sendMagicLinkBody = `      await emailClient.send({
+        to: email,
+        subject: "Sign in to ${config.projectName}",
+        react: MagicLinkEmail({ url }),
+      });`;
+  } else {
+    sendMagicLinkBody = `      console.log(\`Magic link for \${email}: \${url}\`);`;
+  }
+  return `${imports.join("\n")}
+
+export const initAuth = createAuth({
+  permissions,
+  schema,
+  magicLink: {
+    sendMagicLink: async ({ email, url }) => {
+${sendMagicLinkBody}
+    },
+  },
+  session: { expiresIn: "30d" },
+  defaultRoles: ["member"],
+});
+`;
+}
+
 // src/scaffold.ts
 function scaffold(config) {
   const templatesDir = getTemplatesDir();
@@ -623,6 +660,9 @@ function scaffold(config) {
   writeFile(path2.join(targetDir, "vite.config.ts"), generateViteConfig(config));
   writeFile(path2.join(targetDir, "app", "root.tsx"), generateRootTsx(config));
   writeFile(path2.join(targetDir, "app", "routes.ts"), generateRoutesTs(config));
+  if (config.features.auth) {
+    writeFile(path2.join(targetDir, "app", "auth.setup.server.ts"), generateAuthSetup(config));
+  }
   const devVars = generateDevVars(config);
   if (devVars) {
     writeFile(path2.join(targetDir, ".dev.vars"), devVars);

package/llms.txt

@@ -0,0 +1,151 @@
+# create-cfast
+
+> Scaffold a fully wired Cloudflare Workers + React Router + cfast project in one command.
+
+## When to use
+
+Use `create-cfast` to start a new cfast project. It sets up the project structure, installs selected @cfast packages, generates configuration files (wrangler.toml, env schema, auth setup), and provides working example routes.
+
+## Key concepts
+
+- **Interactive prompts**: Asks for project name, which @cfast packages to include, and UI library choice. Can be fully driven by CLI flags for non-interactive use.
+- **Feature dependency resolution**: Selecting `admin` auto-enables `db`, `ui`, and `auth`. Selecting `auth` auto-enables `db`.
+- **Template overlays**: A base template is copied first, then feature-specific overlays are applied in order: `db`, `auth`, `storage`, `email`, `ui`, `admin`.
+- **Environment-aware secrets**: Creates `.dev.vars` for local development. All secret files are `.gitignore`d.
+
+## API Reference
+
+### CLI usage
+
+```bash
+npm create cfast@latest [project-name] [options]
+```
+
+### CLI flags
+
+```
+--auth       Include @cfast/auth (magic email + passkeys)
+--db         Include @cfast/db (D1 + Drizzle ORM)
+--storage    Include @cfast/storage (R2 file uploads)
+--email      Include @cfast/email (email sending)
+--ui         Include @cfast/ui (components + actions)
+--admin      Include @cfast/admin (admin panel)
+--all        Include all packages
+--help       Show help
+```
+
+When any feature flag is provided, interactive feature selection is skipped.
+
+### Programmatic types
+
+```typescript
+type Features = {
+  auth: boolean; db: boolean; storage: boolean;
+  email: boolean; ui: boolean; admin: boolean;
+};
+
+type UiLibrary = "joy" | "headless";
+
+type Config = {
+  projectName: string;
+  targetDir: string;
+  features: Features;
+  uiLibrary: UiLibrary | null;  // null when ui feature is disabled
+};
+```
+
+### Key internal functions
+
+```typescript
+scaffold(config: Config): void              // main scaffolding entry point
+resolveFeatureDeps(features: Features): Features  // auto-enables dependencies
+resolveConfig(raw: Config): Config          // resolves deps + defaults uiLibrary to "joy"
+parseArgs(argv: string[]): CliArgs          // parses CLI arguments
+promptForConfig(args: CliArgs): Promise<Config | null>  // interactive prompts
+```
+
+### Generators (used internally by `scaffold()`)
+
+```typescript
+generateWranglerToml(config): string
+generateEnv(config): string
+generateCfastServer(config): string
+generateViteConfig(config): string
+generateRootTsx(config): string
+generateRoutesTs(config): string
+generateDevVars(config): string | null
+generateAuthSetup(config): string
+mergePackageJsons(base, overlays): Record<string, unknown>
+```
+
+## Usage Examples
+
+### Interactive
+
+```bash
+npm create cfast@latest my-app
+# Prompts for features, UI library
+# Scaffolds project, prints next steps
+```
+
+### Non-interactive (all features)
+
+```bash
+npm create cfast@latest my-app --all
+# Selects all features, defaults to Joy UI
+```
+
+### Specific features
+
+```bash
+npm create cfast@latest my-app --auth --db --email
+# auth auto-enables db (already selected), skips ui/admin/storage
+```
+
+### After scaffolding
+
+```bash
+cd my-app
+pnpm install
+pnpm dev                    # local dev (wrangler + vite)
+pnpm db:generate            # generate D1 migrations
+pnpm db:migrate:local       # apply migrations locally
+pnpm deploy:staging         # deploy to staging
+pnpm deploy:production      # deploy to production
+```
+
+## Generated project structure
+
+```
+my-app/
+  CLAUDE.md           # LLM-friendly project conventions
+  app/
+    routes/           # _index.tsx, login.tsx, dashboard.tsx
+    db/schema.ts      # Drizzle schema with auth tables
+    auth.ts           # @cfast/auth config
+    permissions.ts    # @cfast/permissions definitions
+    cfast.server.ts   # @cfast/core app setup
+    env.ts            # @cfast/env schema
+    root.tsx          # React root with providers
+    routes.ts         # React Router route config
+  wrangler.toml       # D1, KV bindings pre-configured
+  .dev.vars           # local dev secrets
+  vite.config.ts
+  package.json
+```
+
+## Integration
+
+- Scaffolds wiring for **@cfast/core** (`createApp` + plugins in `cfast.server.ts`).
+- Sets up **@cfast/auth** with magic link and passkey config.
+- Configures **@cfast/db** with Drizzle schema and D1 bindings.
+- Generates **@cfast/env** schema from selected features.
+- When `ui` is selected, sets up **@cfast/ui** with Joy UI or headless plugin.
+- When `admin` is selected, adds admin route using **@cfast/admin**.
+
+## Common Mistakes
+
+- Running in a non-empty directory -- `scaffold()` throws if the target directory exists and is not empty.
+- Expecting `--admin` alone to work without auth/db -- dependencies are auto-resolved, but be aware that admin implies auth + db + ui.
+- Forgetting to set API keys in `.dev.vars` after scaffolding -- the generated file has placeholder comments.
+- Using `npm` instead of `pnpm` for the generated project -- the scaffolded `package.json` expects pnpm.

package/package.json

@@ -1,21 +1,40 @@
 {
   "name": "create-cfast",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Scaffold a fully wired Cloudflare Workers + React Router project with cfast",
+  "keywords": [
+    "cfast",
+    "cloudflare-workers",
+    "create",
+    "scaffold",
+    "react-router"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/DanielMSchmidt/cfast.git",
     "directory": "packages/create-cfast"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "type": "module",
   "bin": {
     "create-cfast": "./dist/index.js"
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "llms.txt"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
+  },
   "dependencies": {
     "kolorist": "^1",
     "prompts": "^2"
@@ -26,12 +45,5 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^3"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm",
-    "dev": "tsup src/index.ts --format esm --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "test": "vitest run"
   }
-}
+}

package/templates/admin/app/routes/admin.tsx

@@ -1,8 +1,10 @@
 import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router";
-import { useLoaderData } from "react-router";
-import { AdminPanel } from "@cfast/admin/client";
-import { joyAdminComponents } from "@cfast/ui/joy";
+import { createAdminComponent, introspectSchema } from "@cfast/admin";
 import { adminLoader, adminAction } from "~/admin.server";
+import * as schema from "~/db/schema";
+
+const tableMetas = introspectSchema(schema);
+const AdminComponent = createAdminComponent(tableMetas);
 
 export async function loader(args: LoaderFunctionArgs) {
   return adminLoader(args.request);
@@ -12,7 +14,4 @@ export async function action(args: ActionFunctionArgs) {
   return adminAction(args.request);
 }
 
-export default function Admin() {
-  const data = useLoaderData<typeof loader>();
-  return <AdminPanel data={data} components={joyAdminComponents} />;
-}
+export default AdminComponent;

package/templates/auth/app/routes/login.tsx

@@ -1,7 +1,7 @@
 import type { LoaderFunctionArgs } from "react-router";
 import { redirect, useLoaderData } from "react-router";
 import { LoginPage } from "@cfast/auth/client";
-import { joyLoginComponents } from "@cfast/ui/joy";
+import { joyLoginComponents } from "@cfast/joy";
 import { getUser } from "~/auth.helpers.server";
 import { authClient } from "~/auth.client";
 

package/templates/base/CLAUDE.md

@@ -0,0 +1,143 @@
+# {{projectName}}
+
+Built with [cfast](https://github.com/DanielMSchmidt/cfast) — Cloudflare Workers + React Router 7 + Drizzle ORM + D1.
+
+## Architecture
+
+- **Runtime:** Cloudflare Workers
+- **Framework:** React Router v7 (file-based routing)
+- **Database:** Cloudflare D1 via Drizzle ORM
+- **Auth:** @cfast/auth (Better Auth — magic email + passkeys)
+- **Permissions:** @cfast/permissions (isomorphic, DB-enforced)
+- **UI:** @cfast/ui + @cfast/forms (schema-derived)
+
+## Key Conventions
+
+### Permissions are DB-enforced — never check manually in route handlers
+
+Permissions are defined once in `app/permissions.ts` and enforced automatically by `@cfast/db`.
+Do NOT add manual permission checks in loaders/actions. The DB layer rejects unauthorized queries.
+
+### Use @cfast/actions for route actions
+
+Actions are defined in `app/actions.server.ts` using `createAction` and composed with `composeActions`.
+Do NOT use raw React Router `action` functions with manual request parsing.
+
+### Forms are schema-derived
+
+Use `@cfast/forms` to generate forms from Drizzle schema columns.
+Customize with field overrides — do NOT rewrite forms from scratch.
+
+### Use @cfast/db for all database operations
+
+`@cfast/db` wraps Drizzle with permission-aware, lazy queries.
+Do NOT use raw Drizzle `db.select()` / `db.insert()` calls directly.
+
+### Auth is pre-configured
+
+Use `requireUser(request)` or `requireAuthContext(request)` from `~/auth.helpers.server` for protected routes.
+Do NOT build custom auth flows.
+
+### File uploads use @cfast/storage
+
+Schema-defined file types with R2 storage. Do NOT write custom upload handlers.
+
+## Common Tasks
+
+### Add a new entity
+
+1. Define the table in `app/db/schema.ts` (Drizzle `sqliteTable`)
+2. Run `pnpm db:generate` then `pnpm db:migrate:local`
+3. Add permission grants in `app/permissions.ts`
+4. Create actions in a `*.server.ts` file using `createAction` from `~/actions.server`
+5. Create the route in `app/routes/` using `composeActions` for the action export
+
+### Add a new page/route
+
+1. Create a file in `app/routes/` (React Router file-based routing)
+2. Export a `loader` for data fetching, `action` via `composeActions` for mutations
+3. Export a default component for the UI
+
+### Add a new action to an existing route
+
+1. Define the action with `createAction` in the route's `*.server.ts` file
+2. Add it to the existing `composeActions` call
+3. Use `<ActionButton>` or a form with the action's `intent` hidden field in the UI
+
+### Add a table to the admin panel
+
+1. Import the table from `~/db/schema` in `app/admin.server.ts`
+2. Add it to the `schema` object in the admin config
+3. Optionally add dashboard widgets in the `dashboard.widgets` array
+
+### Customize form fields
+
+Use field overrides when calling the form generator:
+```ts
+// Override specific fields, keep the rest auto-generated
+{ fields: { title: { label: "Item Name", placeholder: "Enter name..." } } }
+```
+
+## Anti-Patterns — Do NOT Do These
+
+| Instead of... | Do this |
+|---|---|
+| Manual permission checks in loaders/actions | Define grants in `permissions.ts` — DB enforces them |
+| `<PermissionGate>` with custom logic | Use `<PermissionGate>` with the grant system or action permission status |
+| Raw Drizzle `db.select()`/`db.insert()` | Use `@cfast/db` operations (permission-aware) |
+| Raw SQL queries | Use `@cfast/db` operations |
+| Custom auth middleware or flows | Use `requireUser()` / `requireAuthContext()` from `~/auth.helpers.server` |
+| Hand-writing full form markup | Use `@cfast/forms` with schema derivation + field overrides |
+| Custom file upload endpoints | Use `@cfast/storage` with schema-defined file types |
+| Manual `request.formData()` parsing in actions | Use `createAction` which handles parsing, validation, and permissions |
+| `hasRole()` / `hasAnyRole()` checks | Use `can()` from `@cfast/permissions` to check permissions |
+| Manually adding hidden `<input>` fields to forms | Use `<ActionForm>` which injects hidden fields (e.g. `intent`) automatically |
+
+## Project Structure
+
+```
+app/
+├── routes/             # React Router file-based routes
+├── db/
+│   ├── schema.ts       # Drizzle schema (source of truth)
+│   └── client.ts       # DB client factory
+├── permissions.ts      # Permission definitions
+├── auth.helpers.server.ts  # Auth utilities (requireUser, etc.)
+├── auth.setup.server.ts    # Auth initialization
+├── cfast.server.ts     # App context setup
+├── actions.server.ts   # Shared action factory
+├── env.ts              # Type-safe env bindings
+└── root.tsx            # App root layout
+workers/
+└── app.ts              # Cloudflare Worker entry point
+wrangler.toml           # Cloudflare config (D1, KV, R2 bindings)
+drizzle.config.ts       # Drizzle Kit config
+```
+
+## Commands
+
+```bash
+pnpm dev                    # Start local dev server
+pnpm build                  # Production build
+pnpm db:generate            # Generate migrations from schema changes
+pnpm db:migrate:local       # Apply migrations locally
+pnpm db:migrate:remote      # Apply migrations to remote D1
+pnpm deploy:staging         # Deploy to staging
+pnpm deploy:production      # Deploy to production
+```
+
+## Keeping LLM Documentation Updated
+
+When adding or changing public APIs in any `@cfast` package:
+- Update the package's `llms.txt` with the new/changed API signatures, examples, and integration notes
+- Update the root `llms.txt` (concise overview) and `llms-full.txt` (complete reference) if the change affects cross-package patterns or the mental model
+- The scaffolded `CLAUDE.md` (this file's template in `create-cfast`) should be updated if conventions change
+
+## Package Documentation
+
+For detailed API reference on any cfast package, check:
+`node_modules/@cfast/[package]/llms.txt`
+
+Available packages: `@cfast/env`, `@cfast/permissions`, `@cfast/auth`, `@cfast/db`,
+`@cfast/actions`, `@cfast/ui`, `@cfast/forms`, `@cfast/pagination`, `@cfast/storage`,
+`@cfast/email`, `@cfast/admin`.

package/templates/email/app/email/templates/magic-link.tsx

@@ -0,0 +1,17 @@
+import { Html, Head, Body, Text, Link } from "@react-email/components";
+
+type MagicLinkEmailProps = {
+  url: string;
+};
+
+export function MagicLinkEmail({ url }: MagicLinkEmailProps) {
+  return (
+    <Html>
+      <Head />
+      <Body>
+        <Text>Click the link below to sign in:</Text>
+        <Link href={url}>Sign in to {{projectName}}</Link>
+      </Body>
+    </Html>
+  );
+}

package/templates/ui/package.json

@@ -1,6 +1,7 @@
 {
   "dependencies": {
     "@cfast/actions": "^0.1.0",
+    "@cfast/joy": "^0.1.0",
     "@cfast/ui": "^0.1.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Daniel Schmidt
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/templates/auth/app/auth.setup.server.ts

@@ -1,17 +0,0 @@
-import { createAuth } from "@cfast/auth";
-import * as schema from "./db/schema";
-import { permissions } from "./permissions";
-import { env } from "./env";
-
-export const initAuth = createAuth({
-  permissions,
-  schema,
-  magicLink: {
-    sendMagicLink: async ({ email, url }) => {
-      // TODO: integrate with @cfast/email when email feature is enabled
-      console.log(`Magic link for ${email}: ${url}`);
-    },
-  },
-  session: { expiresIn: "30d" },
-  defaultRoles: ["member"],
-});