@fluid-app/fluid-cli-portal 0.1.0

package/templates/fullstack/Dockerfile

@@ -0,0 +1,44 @@
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+
+# Install dependencies
+RUN corepack enable && pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build frontend (Vite) and server (esbuild)
+RUN pnpm run build
+
+# Collect production files into a staging directory for clean cross-stage copy
+RUN mkdir /staging && cp package.json pnpm-lock.yaml /staging/
+
+# --- Production stage ---
+FROM node:20-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=8080
+
+# Copy build outputs and migration files
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/drizzle ./drizzle
+
+# Copy package + lock files for production install
+COPY --from=builder /staging ./
+
+# Install production dependencies only (@libsql/client needs node_modules)
+RUN corepack enable && pnpm install --prod --frozen-lockfile
+
+RUN addgroup --system --gid 1001 appgroup && \
+    adduser --system --uid 1001 --ingroup appgroup appuser
+USER appuser
+
+EXPOSE 8080
+
+CMD ["node", "dist/server/entry.js"]

package/templates/fullstack/README.md.template

@@ -0,0 +1,176 @@
+# {{projectName}}
+
+A Fluid Commerce Portal built with the **Fullstack** template — includes [Hono](https://hono.dev/) API server, [Drizzle ORM](https://orm.drizzle.team/), and SQLite for a complete frontend + backend setup.
+
+## What's Included
+
+### Frontend
+
+- [React 19](https://react.dev/) with [TypeScript](https://www.typescriptlang.org/)
+- [Vite](https://vite.dev/) for fast development and optimized builds
+- [Tailwind CSS 4](https://tailwindcss.com/) for utility-first styling
+- [TanStack Query](https://tanstack.com/query) for data fetching and caching
+- [Fluid Portal SDK](https://github.com/fluidcommerce) for Fluid Commerce integration
+- Pre-configured navigation, screen routing, and dashboard widgets
+
+### Backend
+
+- [Hono](https://hono.dev/) — lightweight, fast API server integrated with Vite dev server
+- [Drizzle ORM](https://orm.drizzle.team/) — type-safe SQL with zero overhead
+- [libSQL](https://github.com/tursodatabase/libsql-client-ts) — SQLite-compatible database, works locally and with [Turso](https://turso.tech/)
+- Example CRUD routes (`/api/todos`) to get started quickly
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Push the database schema (creates the SQLite database)
+pnpm db:push
+
+# Start the development server
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) to view your portal. _(Port may differ if 5173 is in use — check the dev server output.)_
+
+### Other Commands
+
+```bash
+pnpm build       # Build for production (frontend + server)
+pnpm start       # Start the production server
+pnpm preview     # Preview production build via Vite
+pnpm typecheck   # Run TypeScript type checking
+pnpm lint        # Run ESLint
+```
+
+## Database Setup
+
+This template uses SQLite with Drizzle ORM. The database is stored as a local file (`local.db`).
+
+```bash
+# Create or update the database schema from your Drizzle schema definitions
+pnpm db:push
+
+# Open Drizzle Studio to browse and edit your data
+pnpm db:studio
+
+# Generate SQL migration files (for production workflows)
+pnpm db:generate
+
+# Run pending migrations
+pnpm db:migrate
+```
+
+Edit the schema in `src/server/db/schema.ts`, then run `pnpm db:push` to apply changes during development.
+
+## Project Structure
+
+```
+src/
+├── main.tsx              # App entry with FluidProvider setup
+├── App.tsx               # Main app with screen routing
+├── index.css             # Global styles (Tailwind CSS)
+├── fluid.config.ts       # Fluid SDK configuration
+├── portal.config.ts      # Navigation and screen registration
+├── navigation/
+│   └── index.tsx         # Sidebar navigation component
+├── screens/
+│   └── Dashboard.tsx     # Dashboard with widgets
+└── server/
+    ├── index.ts          # Hono app (mounts routes, exported for dev + prod)
+    ├── entry.ts          # Production server entry (Node.js + static serving)
+    ├── routes/
+    │   └── index.ts      # Example CRUD routes (/api/todos)
+    └── db/
+        ├── index.ts      # Database connection
+        ├── migrate.ts    # Auto-migration on server start
+        └── schema.ts     # Drizzle schema definitions
+```
+
+## Adding API Routes
+
+Create a new route file in `src/server/routes/` and mount it in `src/server/index.ts`:
+
+```typescript
+// src/server/routes/products.ts
+import { Hono } from "hono";
+
+export const productRoutes = new Hono();
+
+productRoutes.get("/", async (c) => {
+  // your logic here
+  return c.json({ products: [] });
+});
+```
+
+```typescript
+// src/server/index.ts
+import { productRoutes } from "./routes/products";
+
+app.route("/api/products", productRoutes);
+```
+
+## Using Turso (Cloud Database)
+
+This template uses `@libsql/client`, which works with both local SQLite files and [Turso](https://turso.tech/) cloud databases. To use Turso:
+
+1. Create a Turso database: `turso db create my-app`
+2. Get the connection URL: `turso db show my-app --url`
+3. Create an auth token: `turso db tokens create my-app`
+4. Set `DATABASE_URL` and `DATABASE_AUTH_TOKEN` in your `.env` file
+
+## Docker
+
+Build and run with Docker:
+
+```bash
+docker build -t {{projectName}} .
+docker run -p 8080:8080 -e DATABASE_URL=<your-turso-url> -e DATABASE_AUTH_TOKEN=<your-token> {{projectName}}
+```
+
+Database migrations run automatically when the server starts, so the database schema is always up to date.
+
+## CI/CD
+
+This project includes GitHub Actions workflows for automated checks and deployment.
+
+### Pull Request Checks
+
+Every pull request runs typecheck and lint automatically. See `.github/workflows/ci.yml`.
+
+### Deployment
+
+Pushes to `main` automatically deploy to Cloud Run. To set this up:
+
+1. **Run initial deploy locally** (provisions Turso database + first Cloud Run deploy):
+   ```bash
+   fluid deploy
+   ```
+
+2. **Note the database credentials** from the deploy output (DATABASE_URL and DATABASE_AUTH_TOKEN)
+
+3. **Add GitHub repository secrets** (Settings > Secrets and variables > Actions):
+   - `GCP_SA_JSON` — GCP service account key JSON ([create one](https://cloud.google.com/iam/docs/creating-managing-service-account-keys))
+   - `DATABASE_URL` — Turso database URL from step 1
+   - `DATABASE_AUTH_TOKEN` — Turso auth token from step 1
+
+4. **Add GitHub repository variables** (Settings > Secrets and variables > Actions > Variables):
+   - `GCP_PROJECT` — Your GCP project ID
+   - `CLOUD_RUN_REGION` — Cloud Run region (default: `us-central1`)
+
+5. **Push to main** — deployment happens automatically
+
+## Styling
+
+This project uses [Tailwind CSS 4](https://tailwindcss.com/) for styling. The global styles are imported in `src/index.css`. You can customize the theme and add utilities there.
+
+## Learn More
+
+- [Fluid Portal SDK Documentation](https://github.com/fluidcommerce)
+- [Hono Documentation](https://hono.dev/)
+- [Drizzle ORM Documentation](https://orm.drizzle.team/)
+- [Vite Documentation](https://vite.dev/)
+- [React Documentation](https://react.dev/)
+- [Tailwind CSS Documentation](https://tailwindcss.com/)

package/templates/fullstack/drizzle/0000_initial.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS `todos` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`title` text NOT NULL,
+	`completed` integer DEFAULT false NOT NULL,
+	`created_at` text DEFAULT (current_timestamp) NOT NULL,
+	`updated_at` text DEFAULT (current_timestamp) NOT NULL
+);

package/templates/fullstack/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,63 @@
+{
+  "id": "00000000-0000-0000-0000-000000000000",
+  "prevId": "",
+  "version": "6",
+  "dialect": "sqlite",
+  "tables": {
+    "todos": {
+      "name": "todos",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "completed": {
+          "name": "completed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(current_timestamp)"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(current_timestamp)"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "enums": {},
+  "views": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  }
+}

package/templates/fullstack/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1737000000000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/fullstack/drizzle.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "drizzle-kit";
+
+const url = process.env.DATABASE_URL ?? "file:local.db";
+const isLocal = url.startsWith("file:") || url === ":memory:";
+
+export default defineConfig({
+  schema: "./src/server/db/schema.ts",
+  out: "./drizzle",
+  dialect: isLocal ? "sqlite" : "turso",
+  dbCredentials: isLocal
+    ? { url }
+    : { url, authToken: process.env.DATABASE_AUTH_TOKEN },
+});

package/templates/fullstack/esbuild.config.js

@@ -0,0 +1,14 @@
+import { build } from "esbuild";
+
+await build({
+  entryPoints: ["src/server/entry.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node20",
+  format: "esm",
+  outfile: "dist/server/entry.js",
+  external: ["@libsql/client", "drizzle-orm"],
+  banner: {
+    js: 'import { createRequire } from "module"; const require = createRequire(import.meta.url);',
+  },
+});

package/templates/fullstack/eslint.config.js

@@ -0,0 +1,13 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import reactHooks from "eslint-plugin-react-hooks";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    plugins: { "react-hooks": reactHooks },
+    rules: reactHooks.configs.recommended.rules,
+  },
+  { ignores: ["dist/", "*.config.*"] },
+);

package/templates/fullstack/package.json.template

@@ -0,0 +1,63 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && node esbuild.config.js",
+    "start": "node dist/server/entry.js",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "deploy": "fluid deploy",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@fluid-app/portal-sdk": "{{sdkVersion}}",
+    "@fortawesome/fontawesome-svg-core": "^6.7.2",
+    "@fortawesome/pro-regular-svg-icons": "^6.7.2",
+    "@fortawesome/react-fontawesome": "^0.2.2",
+    "@tanstack/react-query": "^5.90.0",
+    "@hono/node-server": "^1.13.0",
+    "@libsql/client": "^0.17.0",
+    "drizzle-orm": "^0.44.0",
+    "hono": "^4.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.55.0",
+    "@hookform/resolvers": "^4.1.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@fluid-app/fluid-cli-portal": "{{sdkVersion}}",
+    "@eslint/js": "^9.0.0",
+    "@hono/vite-dev-server": "^0.25.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "esbuild": "^0.25.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "drizzle-kit": "^0.31.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.4.1",
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

package/templates/fullstack/src/fluid.config.ts.template

@@ -0,0 +1,69 @@
+import type { FluidSDKConfig, FluidAuthConfig } from "@fluid-app/portal-sdk";
+import { getStoredToken } from "@fluid-app/portal-sdk";
+
+/**
+ * Fluid SDK Configuration
+ *
+ * This file contains the configuration for connecting to your Fluid Commerce account.
+ * Authentication is handled by FluidAuthProvider, which automatically:
+ * - Extracts tokens from URL parameters (passed by parent Fluid app)
+ * - Stores tokens in cookies and localStorage
+ * - Validates token expiration
+ */
+
+/**
+ * Authentication configuration
+ *
+ * Pattern: safety-satisfies-over-type-annotation
+ * Using `satisfies FluidAuthConfig` validates the object shape against the type
+ * WITHOUT widening the inferred types. This means:
+ *   - TypeScript checks that all required properties are present
+ *   - TypeScript checks that property types are compatible
+ *   - The actual inferred types remain as specific as possible
+ *
+ * Compare to type annotation (`const authConfig: FluidAuthConfig = {...}`):
+ * - Type annotation widens types to match the interface exactly
+ * - `satisfies` preserves literal types while validating structure
+ */
+export const authConfig = {
+  /**
+   * Enable dev-mode auth bypass for local development.
+   * This lets you run the portal without a real JWT token.
+   * Only active in Vite dev mode (pnpm dev) - automatically disabled in production builds.
+   */
+  devBypass: true,
+
+  // Auth failure defaults: SDK automatically redirects to https://auth.fluid.app
+  // with a redirect_url back to the current page. To customize:
+  //   onAuthFailure: () => { window.location.href = "/custom-login"; },
+  //   authUrl: "https://custom-auth.example.com",
+} satisfies FluidAuthConfig;
+
+/**
+ * API client configuration
+ *
+ * Pattern: safety-satisfies-over-type-annotation
+ * See authConfig above for explanation of the `satisfies` pattern.
+ *
+ * This config is passed to FluidProvider to configure the API client.
+ * The callbacks (getAuthToken, onAuthError) are called by the SDK
+ * when making API requests.
+ */
+export const fluidConfig = {
+  /**
+   * Base URL for the Fluid API
+   * Change this to your Fluid instance URL if self-hosted
+   */
+  baseUrl: import.meta.env.VITE_API_URL ?? "https://api.fluid.app",
+
+  /**
+   * Returns the authentication token for API requests
+   * This reads from the token stored by FluidAuthProvider
+   */
+  getAuthToken: () => {
+    return getStoredToken() ?? null;
+  },
+
+  // 401 errors default: SDK automatically redirects to https://auth.fluid.app
+  // To customize: onAuthError: () => { clearTokens(); window.location.reload(); },
+} satisfies FluidSDKConfig;

package/templates/fullstack/src/server/db/index.ts

@@ -0,0 +1,10 @@
+import { createClient } from "@libsql/client";
+import { drizzle } from "drizzle-orm/libsql";
+import * as schema from "./schema";
+
+const client = createClient({
+  url: process.env.DATABASE_URL ?? "file:local.db",
+  authToken: process.env.DATABASE_AUTH_TOKEN,
+});
+
+export const db = drizzle(client, { schema });

package/templates/fullstack/src/server/db/migrate.ts

@@ -0,0 +1,12 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { migrate } from "drizzle-orm/libsql/migrator";
+import { db } from "./index";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function runMigrations() {
+  await migrate(db, {
+    migrationsFolder: resolve(__dirname, "../../../drizzle"),
+  });
+}

package/templates/fullstack/src/server/db/schema.ts

@@ -0,0 +1,14 @@
+import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";
+import { sql } from "drizzle-orm";
+
+export const todos = sqliteTable("todos", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at")
+    .notNull()
+    .default(sql`(current_timestamp)`),
+  updatedAt: text("updated_at")
+    .notNull()
+    .default(sql`(current_timestamp)`),
+});

package/templates/fullstack/src/server/entry.ts

@@ -0,0 +1,59 @@
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { runMigrations } from "./db/migrate";
+import app from "./index";
+
+// Run database migrations before starting the server
+try {
+  await runMigrations();
+} catch (error) {
+  console.error("Failed to run database migrations:", error);
+  console.error(
+    "Ensure DATABASE_URL and DATABASE_AUTH_TOKEN are set correctly.",
+  );
+  process.exit(1);
+}
+
+// Cache immutable hashed assets for 1 year
+app.use("/assets/*", async (c, next) => {
+  await next();
+  c.header("Cache-Control", "public, max-age=31536000, immutable");
+});
+
+// Serve static frontend assets from dist/public/
+app.use("/*", serveStatic({ root: "./dist/public" }));
+
+// SPA fallback — serve index.html for all unmatched routes
+app.get("*", serveStatic({ root: "./dist/public", path: "index.html" }));
+
+const port = Number(process.env.PORT) || 8080;
+
+const server = serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`Server listening on http://localhost:${info.port}`);
+});
+
+server.on("error", (err: NodeJS.ErrnoException) => {
+  if (err.code === "EADDRINUSE") {
+    console.error(`\nPort ${port} is already in use.`);
+    console.error(
+      `Try: PORT=${port === 8080 ? 3001 : port + 1} node dist/server/entry.js\n`,
+    );
+    process.exit(1);
+  }
+  throw err;
+});
+
+// Graceful shutdown
+function shutdown() {
+  console.log("Shutting down gracefully...");
+  server.close();
+  const forceExit = setTimeout(() => {
+    console.error("Forcing shutdown after timeout");
+    process.exit(1);
+  }, 10_000);
+  // Allow the process to exit naturally if close finishes before timeout
+  forceExit.unref();
+}
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

package/templates/fullstack/src/server/index.ts

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { secureHeaders } from "hono/secure-headers";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import { apiRoutes } from "./routes/index";
+
+const app = new Hono();
+
+// Security middleware
+app.use("*", secureHeaders());
+app.use(
+  "/api/*",
+  cors({
+    origin: process.env.ALLOWED_ORIGIN ?? "http://localhost:5173",
+  }),
+);
+
+// Logging
+app.use("*", logger());
+
+// Global error handler
+app.onError((err, c) => {
+  console.error(err);
+  return c.json({ error: "Internal server error" }, 500);
+});
+
+// Health check
+app.get("/api/health", (c) => c.json({ status: "ok" }));
+
+// Mount API routes
+app.route("/api", apiRoutes);
+
+export default app;