create-cfast 0.0.1

package/templates/admin/app/admin.server.ts

@@ -0,0 +1,87 @@
+import { createAdminLoader, createAdminAction, introspectSchema } from "@cfast/admin";
+import type { AdminAuthConfig, AdminUser } from "@cfast/admin";
+import { createDb } from "@cfast/db";
+import type { DbConfig } from "@cfast/db";
+import { requireAuthContext, hasRole } from "~/auth.helpers.server";
+import { initAuth } from "~/auth.setup.server";
+import { env } from "~/env";
+import * as schema from "~/db/schema";
+
+const auth: AdminAuthConfig = {
+  async requireUser(request: Request) {
+    const ctx = await requireAuthContext(request);
+    const user: AdminUser = {
+      id: ctx.user.id,
+      email: ctx.user.email,
+      name: ctx.user.name,
+      avatarUrl: null,
+      roles: ctx.user.roles,
+    };
+    return { user, grants: ctx.grants };
+  },
+
+  hasRole(user: AdminUser, role: string) {
+    return hasRole(
+      user as Parameters<typeof hasRole>[0],
+      role as Parameters<typeof hasRole>[1],
+    );
+  },
+
+  async getRoles(userId: string) {
+    const e = env.get();
+    const authInstance = initAuth({ d1: e.DB, appUrl: e.APP_URL });
+    return authInstance.getRoles(userId);
+  },
+
+  async setRole(userId: string, role: string) {
+    const e = env.get();
+    const authInstance = initAuth({ d1: e.DB, appUrl: e.APP_URL });
+    await authInstance.setRole(userId, role);
+  },
+
+  async removeRole(userId: string, role: string) {
+    const e = env.get();
+    const authInstance = initAuth({ d1: e.DB, appUrl: e.APP_URL });
+    await authInstance.removeRole(userId, role);
+  },
+
+  async setRoles(userId: string, roles: string[]) {
+    const e = env.get();
+    const authInstance = initAuth({ d1: e.DB, appUrl: e.APP_URL });
+    await authInstance.setRoles(userId, roles);
+  },
+};
+
+function createDbForAdmin(grants: unknown[], user: { id: string } | null) {
+  const e = env.get();
+  return createDb({
+    d1: e.DB,
+    schema: schema as unknown as DbConfig["schema"],
+    grants: grants as Parameters<typeof createDb>[0]["grants"],
+    user,
+    cache: false,
+  });
+}
+
+const adminConfig = {
+  db: createDbForAdmin,
+  auth,
+  schema: {
+    items: schema.items,
+  },
+  users: {
+    assignableRoles: ["admin", "member"],
+  },
+  dashboard: {
+    widgets: [
+      { type: "count" as const, table: "items", label: "Total Items" },
+      { type: "recent" as const, table: "items", label: "Recent Items", limit: 5 },
+    ],
+  },
+  requiredRole: "admin",
+};
+
+const tableMetas = introspectSchema(adminConfig.schema);
+
+export const adminLoader = createAdminLoader(adminConfig, tableMetas);
+export const adminAction = createAdminAction(adminConfig, tableMetas);

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

@@ -0,0 +1,18 @@
+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 { adminLoader, adminAction } from "~/admin.server";
+
+export async function loader(args: LoaderFunctionArgs) {
+  return adminLoader(args.request);
+}
+
+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} />;
+}

package/templates/admin/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@cfast/admin": "^0.1.0",
+    "nanoid": "^5.1.0"
+  }
+}

package/templates/auth/app/auth.client.ts

@@ -0,0 +1,6 @@
+import { createAuthClient, magicLinkClient } from "@cfast/auth/client";
+import { passkeyClient } from "@better-auth/passkey/client";
+
+export const authClient = createAuthClient({
+  plugins: [magicLinkClient(), passkeyClient()],
+});

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

@@ -0,0 +1,35 @@
+import { initAuth } from "./auth.setup.server";
+import { env } from "./env";
+import type { Grant } from "@cfast/permissions";
+import type { AuthUser } from "./permissions";
+
+export { hasRole, hasAnyRole } from "./permissions";
+export type { UserRole } from "./permissions";
+
+export type AuthContext = { user: AuthUser | null; grants: Grant[] };
+export type AuthenticatedContext = { user: AuthUser; grants: Grant[] };
+
+function getAuth() {
+  const e = env.get();
+  return initAuth({ d1: e.DB, appUrl: e.APP_URL });
+}
+
+export async function getAuthContext(request: Request): Promise<AuthContext> {
+  const ctx = await getAuth().createContext(request);
+  return ctx as AuthContext;
+}
+
+export async function requireAuthContext(request: Request): Promise<AuthenticatedContext> {
+  const ctx = await getAuth().requireUser(request);
+  return ctx as AuthenticatedContext;
+}
+
+export async function getUser(request: Request): Promise<AuthUser | null> {
+  const ctx = await getAuthContext(request);
+  return ctx.user;
+}
+
+export async function requireUser(request: Request): Promise<AuthUser> {
+  const ctx = await requireAuthContext(request);
+  return ctx.user;
+}

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

@@ -0,0 +1,17 @@
+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"],
+});

package/templates/auth/app/db/schema.ts

@@ -0,0 +1,106 @@
+import { relations } from "drizzle-orm";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+// Auth tables (required by Better Auth + @cfast/auth)
+export const users = sqliteTable("users", {
+  id: text("id").primaryKey(),
+  email: text("email").notNull().unique(),
+  name: text("name").notNull(),
+  avatarUrl: text("avatar_url"),
+  emailVerified: integer("email_verified", { mode: "boolean" }).notNull().default(false),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+export const sessions = sqliteTable("sessions", {
+  id: text("id").primaryKey(),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(),
+  token: text("token").notNull().unique(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+export const accounts = sqliteTable("accounts", {
+  id: text("id").primaryKey(),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  accessTokenExpiresAt: integer("access_token_expires_at", { mode: "timestamp" }),
+  refreshTokenExpiresAt: integer("refresh_token_expires_at", { mode: "timestamp" }),
+  scope: text("scope"),
+  idToken: text("id_token"),
+  password: text("password"),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+export const verifications = sqliteTable("verifications", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+export const passkeys = sqliteTable("passkeys", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  publicKey: text("public_key").notNull(),
+  credentialId: text("credential_id").notNull().unique(),
+  counter: integer("counter").notNull().default(0),
+  deviceType: text("device_type"),
+  backedUp: integer("backed_up", { mode: "boolean" }).default(false),
+  transports: text("transports"),
+  createdAt: integer("created_at", { mode: "timestamp" }).$defaultFn(() => new Date()),
+});
+
+export const roles = sqliteTable("roles", {
+  id: text("id").primaryKey(),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  role: text("role").notNull(),
+  grantedBy: text("granted_by").references(() => users.id),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+// App tables — add your own here
+export const items = sqliteTable("items", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content").notNull().default(""),
+  authorId: text("author_id").notNull().references(() => users.id),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+
+// Relations
+export const usersRelations = relations(users, ({ many }) => ({
+  items: many(items),
+  roles: many(roles),
+}));
+
+export const itemsRelations = relations(items, ({ one }) => ({
+  author: one(users, { fields: [items.authorId], references: [users.id] }),
+}));
+
+export const sessionsRelations = relations(sessions, ({ one }) => ({
+  user: one(users, { fields: [sessions.userId], references: [users.id] }),
+}));
+
+export const accountsRelations = relations(accounts, ({ one }) => ({
+  user: one(users, { fields: [accounts.userId], references: [users.id] }),
+}));
+
+export const passkeysRelations = relations(passkeys, ({ one }) => ({
+  user: one(users, { fields: [passkeys.userId], references: [users.id] }),
+}));
+
+export const rolesRelations = relations(roles, ({ one }) => ({
+  user: one(users, { fields: [roles.userId], references: [users.id] }),
+}));

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

@@ -0,0 +1,10 @@
+import { createAuthRouteHandlers } from "@cfast/auth";
+import { initAuth } from "~/auth.setup.server";
+import { env } from "~/env";
+
+const { loader, action } = createAuthRouteHandlers(() => {
+  const e = env.get();
+  return initAuth({ d1: e.DB, appUrl: e.APP_URL });
+});
+
+export { loader, action };

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

@@ -0,0 +1,25 @@
+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 { getUser } from "~/auth.helpers.server";
+import { authClient } from "~/auth.client";
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const user = await getUser(request);
+  if (user) throw redirect("/");
+  return {};
+}
+
+export default function Login() {
+  useLoaderData<typeof loader>();
+
+  return (
+    <LoginPage
+      authClient={authClient}
+      components={joyLoginComponents}
+      title="Sign In"
+      subtitle="Sign in to {{projectName}}"
+    />
+  );
+}

package/templates/auth/package.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": {
+    "@cfast/auth": "^0.1.0",
+    "@better-auth/drizzle-adapter": "^1.5.3",
+    "@better-auth/passkey": "^1.5.3",
+    "better-auth": "^1.2.0"
+  }
+}

package/templates/base/_gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.env
+/node_modules/
+*.tsbuildinfo
+
+# React Router
+/.react-router/
+/build/
+
+# Cloudflare
+.mf
+.wrangler
+.dev.vars*
+worker-configuration.d.ts

package/templates/base/app/entry.server.tsx

@@ -0,0 +1,38 @@
+import type { AppLoadContext, EntryContext } from "react-router";
+import { ServerRouter } from "react-router";
+import { isbot } from "isbot";
+import { renderToReadableStream } from "react-dom/server";
+
+export default async function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  routerContext: EntryContext,
+  _loadContext: AppLoadContext,
+) {
+  let shellRendered = false;
+  const userAgent = request.headers.get("user-agent");
+
+  const body = await renderToReadableStream(
+    <ServerRouter context={routerContext} url={request.url} />,
+    {
+      onError(error: unknown) {
+        responseStatusCode = 500;
+        if (shellRendered) {
+          console.error(error);
+        }
+      },
+    },
+  );
+  shellRendered = true;
+
+  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
+    await body.allReady;
+  }
+
+  responseHeaders.set("Content-Type", "text/html");
+  return new Response(body, {
+    headers: responseHeaders,
+    status: responseStatusCode,
+  });
+}

package/templates/base/app/permissions.ts

@@ -0,0 +1,32 @@
+import { definePermissions } from "@cfast/permissions";
+
+export type UserRole = "admin" | "member";
+
+export type AuthUser = {
+  id: string;
+  email: string;
+  name: string;
+  roles: UserRole[];
+};
+
+const appRoles = ["member", "admin"] as const;
+
+export const permissions = definePermissions<AuthUser>()({
+  roles: appRoles,
+  hierarchy: {
+    admin: ["member"],
+  },
+  grants: (grant) => ({
+    member: [],
+    admin: [grant("manage", "all")],
+  }),
+});
+
+export function hasRole(user: AuthUser, role: UserRole): boolean {
+  if (user.roles.includes("admin")) return true;
+  return user.roles.includes(role);
+}
+
+export function hasAnyRole(user: AuthUser, checkRoles: UserRole[]): boolean {
+  return checkRoles.some((role) => hasRole(user, role));
+}

package/templates/base/app/routes/_index.tsx

@@ -0,0 +1,8 @@
+export default function Index() {
+  return (
+    <div style={{ fontFamily: "system-ui, sans-serif", padding: "2rem", maxWidth: "600px", margin: "0 auto" }}>
+      <h1>Welcome to {{projectName}}</h1>
+      <p>Get started by editing <code>app/routes/_index.tsx</code></p>
+    </div>
+  );
+}

package/templates/base/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "react-router build",
+    "dev": "react-router dev",
+    "preview": "pnpm run build && vite preview",
+    "typecheck": "react-router typegen && tsc -b",
+    "deploy:staging": "pnpm run build && wrangler deploy --env staging",
+    "deploy:production": "pnpm run build && wrangler deploy --env production"
+  },
+  "dependencies": {
+    "@cfast/core": "^0.1.0",
+    "@cfast/env": "^0.1.0",
+    "@cfast/permissions": "^0.1.0",
+    "isbot": "^5.1.31",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router": "^7.13.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.27.0",
+    "@cloudflare/workers-types": "^4.20260310.1",
+    "@react-router/dev": "^7.13.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.2",
+    "vite": "^8.0.0",
+    "wrangler": "^4.72.0"
+  }
+}

package/templates/base/react-router.config.ts

@@ -0,0 +1,8 @@
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  future: {
+    v8_viteEnvironmentApi: true,
+  },
+} satisfies Config;

package/templates/base/tsconfig.cloudflare.json

@@ -0,0 +1,26 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    ".react-router/types/**/*",
+    "app/**/*",
+    "app/**/.server/**/*",
+    "app/**/.client/**/*",
+    "workers/**/*",
+    "worker-configuration.d.ts"
+  ],
+  "compilerOptions": {
+    "composite": true,
+    "strict": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["vite/client"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "rootDirs": [".", "./.react-router/types"],
+    "paths": { "~/*": ["./app/*"] },
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  }
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.cloudflare.json" }
+  ],
+  "compilerOptions": {
+    "checkJs": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true
+  }
+}

package/templates/base/tsconfig.node.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["vite.config.ts"],
+  "compilerOptions": {
+    "composite": true,
+    "strict": true,
+    "types": ["node"],
+    "lib": ["ES2022", "DOM"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler"
+  }
+}

package/templates/base/workers/app.ts

@@ -0,0 +1,29 @@
+import { createRequestHandler } from "react-router";
+import { app } from "../app/cfast.server";
+import { env } from "../app/env";
+
+declare module "react-router" {
+  export interface AppLoadContext {
+    cloudflare: {
+      env: Env;
+      ctx: ExecutionContext;
+    };
+  }
+}
+
+type Env = ReturnType<typeof env.get>;
+
+const requestHandler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+  import.meta.env.MODE,
+);
+
+export default {
+  async fetch(request: Request, rawEnv: Record<string, unknown>, ctx: ExecutionContext) {
+    app.init(rawEnv);
+    env.init(rawEnv);
+    return requestHandler(request, {
+      cloudflare: { env: env.get(), ctx },
+    });
+  },
+};

package/templates/db/app/db/client.ts

@@ -0,0 +1,8 @@
+import { drizzle } from "drizzle-orm/d1";
+import * as schema from "./schema";
+
+export function createDbClient(d1: D1Database) {
+  return drizzle(d1, { schema });
+}
+
+export type DbClient = ReturnType<typeof createDbClient>;

package/templates/db/app/db/schema.ts

@@ -0,0 +1,9 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const items = sqliteTable("items", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content").notNull().default(""),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});

package/templates/db/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./app/db/schema.ts",
+  out: "./drizzle",
+  dialect: "sqlite",
+});

package/templates/db/package.json

@@ -0,0 +1,14 @@
+{
+  "dependencies": {
+    "@cfast/db": "^0.1.0",
+    "drizzle-orm": "^0.45.1"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.9"
+  },
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate:local": "wrangler d1 migrations apply DB --local",
+    "db:migrate:remote": "wrangler d1 migrations apply DB --remote"
+  }
+}

package/templates/email/app/email/send.ts

@@ -0,0 +1,10 @@
+import { email } from "~/email.server";
+import { WelcomeEmail } from "./templates/welcome";
+
+export async function sendWelcomeEmail(emailAddress: string, name: string) {
+  await email.send({
+    to: emailAddress,
+    subject: "Welcome to {{projectName}}!",
+    react: WelcomeEmail({ name }),
+  });
+}

package/templates/email/app/email/templates/welcome.tsx

@@ -0,0 +1,19 @@
+interface WelcomeEmailProps {
+  name: string;
+}
+
+export function WelcomeEmail({ name }: WelcomeEmailProps) {
+  return (
+    <html>
+      <head />
+      <body style={{ fontFamily: "sans-serif", padding: "20px" }}>
+        <div style={{ maxWidth: "600px", margin: "0 auto" }}>
+          <h1>Welcome to {{projectName}}!</h1>
+          <p>Hi {name}, your account has been created successfully.</p>
+          <hr />
+          <p style={{ color: "#666", fontSize: "12px" }}>{{projectName}}</p>
+        </div>
+      </body>
+    </html>
+  );
+}

package/templates/email/app/email.server.ts

@@ -0,0 +1,33 @@
+import { createEmailClient } from "@cfast/email";
+import { mailgun } from "@cfast/email/mailgun";
+import { console as consoleProvider } from "@cfast/email/console";
+import type { EmailProvider } from "@cfast/email";
+import { env } from "~/env";
+
+let cachedProvider: EmailProvider | null = null;
+function getProvider(): EmailProvider {
+  if (!cachedProvider) {
+    const e = env.get();
+    if (e.MAILGUN_API_KEY === "test-key") {
+      cachedProvider = consoleProvider();
+    } else {
+      cachedProvider = mailgun(() => ({
+        apiKey: env.get().MAILGUN_API_KEY,
+        domain: env.get().MAILGUN_DOMAIN,
+      }));
+    }
+  }
+  return cachedProvider;
+}
+
+const lazyProvider: EmailProvider = {
+  name: "lazy",
+  send(message) {
+    return getProvider().send(message);
+  },
+};
+
+export const email = createEmailClient({
+  provider: lazyProvider,
+  from: () => `{{projectName}} <noreply@${env.get().MAILGUN_DOMAIN}>`,
+});