create-restack-pattern 0.1.5 → 0.1.7

package/README.md

@@ -15,11 +15,13 @@ npx create-restack-pattern my-app
 ```
 
 Or run it without arguments to be prompted for a project name:
+
 ```bash
 npx create-restack-pattern
 ```
 
 ### Prerequisites
+
 - **Node.js**: version 20 or higher
 - **pnpm**: package manager installed (run `npm install -g pnpm` if needed)
 - **PostgreSQL**: a running database (either a local instance or a free hosted instance on [Neon](https://neon.tech))
@@ -31,26 +33,32 @@ npx create-restack-pattern
 Once the CLI finishes scaffolding your project, follow these three simple steps to get started:
 
 ### 1. Configure Environment Variables
+
 ```bash
 cd my-app
 cp backend/.env.example backend/.env
 cp frontend/.env.example frontend/.env
 ```
+
 - Open `backend/.env` and set:
   - `DATABASE_URL` (format: `postgresql://user:password@localhost:5432/dbname`; you can use a local Postgres database or a free hosted instance on [Neon](https://neon.tech))
   - `JWT_SECRET` (generate a secure 32-character key by running: `openssl rand -base64 32`)
-- *(Optional)* Open `frontend/.env` to override `NEXT_PUBLIC_API_URL` (defaults to `http://localhost:3001` for local Hono API).
+- _(Optional)_ Open `frontend/.env` to override `NEXT_PUBLIC_API_URL` (defaults to `http://localhost:3001` for local Hono API).
 
 ### 2. Push Database Tables
+
 This creates the required `users` and `auth_sessions` tables in your database:
+
 ```bash
 pnpm --filter backend db:push
 ```
 
 ### 3. Start Development Servers
+
 ```bash
 pnpm dev
 ```
+
 - **Backend API**: runs at [http://localhost:3001](http://localhost:3001)
 - **Frontend App**: runs at [http://localhost:3000](http://localhost:3000)
 
@@ -95,5 +103,5 @@ Before testing your CLI changes locally or publishing, follow the standard workf
    ```
 
 For detailed guides, workflow explanations, and lessons learned:
+
 - Check out the [Development Guide](../../docs/en/development-guide.md) (Indonesian: [Panduan Kontribusi](../../docs/id/development-guide.md))
-- Check out the [Building a Scaffolding CLI Tutorial](../../docs/tutorial.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-restack-pattern",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Scaffold a new Next.js + Hono + Drizzle monorepo using the Restack Pattern (Semi-DDD) template.",
   "license": "MIT",
   "type": "module",

package/template/AGENTS.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides architecture, build, and styling guidance to Claude Code (claude.ai/code) and other AI assistants working in this repository.
+
+## Project Stack
+- **Frontend**: Next.js 16 (App Router)
+- **Backend**: Hono
+- **ORM**: Drizzle ORM
+- **Database**: PostgreSQL (Postgres-js driver)
+- **Validation**: Zod (shared schemas)
+- **Package Manager**: pnpm workspaces
+
+## Monorepo Layout
+- `frontend/` — Next.js 16 App Router
+- `backend/` — Hono API
+- `packages/shared/` — Shared Zod schemas (the single source of truth)
+
+## Build and Dev Commands
+All commands should be run from the repository root:
+- `pnpm install` — Install all dependencies
+- `pnpm --filter @restack/shared build` — Build shared Zod schemas (run first!)
+- `pnpm --filter backend dev` — Start Hono dev server on port 3001
+- `pnpm --filter frontend dev` — Start Next.js dev server on port 3000
+- `pnpm --filter backend db:push` — Push Drizzle schema to PostgreSQL database
+- `pnpm --filter backend db:studio` — Open Drizzle Studio database viewer
+- `pnpm --filter backend test` — Run Vitest tests
+
+## Architecture Rules: Semi-DDD (Feature-Driven)
+Code is organized by business domain/feature, not by file type.
+
+### Backend Layout (`backend/src/domains/[feature]/`)
+Each domain has 4 primary files:
+- `[feature].routes.ts` — HTTP endpoints & input validation (imports Zod schema from `@restack/shared`)
+- `[feature].service.ts` — Pure business logic only (no direct DB access)
+- `[feature].repo.ts` — Drizzle queries only (no business logic)
+- `[feature].model.ts` — Drizzle table definitions
+
+**Cross-Domain Dependency Rule**: The `auth` domain may import from `user` (e.g. `usersTable` from `user.model.ts`). The reverse (user importing from auth) is STRICTLY FORBIDDEN.
+
+### Frontend Layout (`frontend/domains/[feature]/`)
+- `components/` — UI components (no direct data fetching)
+- `hooks/` — Reactive state & data fetching logic
+- `services/` — Thin HTTP wrappers around `apiClient`
+- `types.ts` — Local TS type declarations
+- `frontend/app/` is strictly for layout, routing config, metadata, or entry gates. Do not implement custom JSX layouts, forms, state, or complex components here. Always delegate rendering to domain feature components.
+
+## Critical Gotcha: Shared Package Build Requirement
+`@restack/shared`'s `package.json` resolves to `dist/`, which is gitignored. When editing Zod schemas in `packages/shared/src/schemas/`, you MUST compile them by running:
+`pnpm --filter @restack/shared build`
+(or keep `pnpm --filter @restack/shared dev` watch mode running in a terminal) or the frontend and backend will fail to resolve the updated types or throw compilation errors.
+
+## Auth & Cookie Strategy
+- Short-lived JWT `access_token` (15m) and opaque `refresh_token` (30d) are both set as `httpOnly` cookies at `Path=/`.
+- Access tokens are automatically refreshed by the client-side `apiClient` on a 401 response.
+- Cookie configuration: `SameSite=None` in production (requires `Secure=true`), and `SameSite=Lax` in development (`Secure=false` since local dev runs on HTTP).
+- There is no server-side auth gate (`middleware.ts`/`proxy.ts`) because cookies cannot be read server-side when frontend and backend deploy to unrelated domains (Topology B). Authenticated routes are protected via backend `requireAuth` middleware, and frontend pages are protected via `<RequireAuth>` or client-side checks in hooks.
+
+## Structured & Correlation Logging
+- Every incoming HTTP request is tagged with a unique `requestId` via Hono's `requestId` middleware.
+- A request-scoped child logger (`logger.child({ requestId })`) is bound to Hono's context.
+- In route handlers, always extract the request-specific child logger from Hono's context (`c.get("logger") || logger`) to log events. This ensures all logs generated during a request carry the correct `requestId` and `userId` context (which is automatically enriched by the `requireAuth` middleware).
+

package/template/backend/src/domains/auth/auth.repo.ts

@@ -1,5 +1,5 @@
 import { and, eq, gt } from "drizzle-orm"
-import { db } from "../../shared/db/index.js"
+import { db } from "../../infra/db/index.js"
 import { usersTable } from "../user/user.model.js"
 import { authSessionsTable } from "./auth.model.js"
 

package/template/backend/src/domains/auth/auth.routes.ts

@@ -5,7 +5,7 @@ import { zValidator } from "@hono/zod-validator"
 import { LoginSchema, RegisterSchema } from "@restack/shared"
 import { authService, ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS } from "./auth.service.js"
 import { env } from "../../config/env.js"
-import { logger, type AppVariables } from "../../shared/logger/logger.js"
+import { logger, type AppVariables } from "../../utils/logger.js"
 
 /**
  * Routing layer for the Auth domain.

package/template/backend/src/domains/user/user.repo.ts

@@ -1,5 +1,5 @@
 import { eq } from "drizzle-orm"
-import { db } from "../../shared/db/index.js"
+import { db } from "../../infra/db/index.js"
 import { usersTable } from "./user.model.js"
 
 export type UserRow = typeof usersTable.$inferSelect

package/template/backend/src/domains/user/user.routes.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeAll, afterAll } from "vitest"
 import { eq } from "drizzle-orm"
 import { userRoutes } from "./user.routes.js"
 import { authService } from "../auth/auth.service.js"
-import { db } from "../../shared/db/index.js"
+import { db } from "../../infra/db/index.js"
 import { usersTable } from "./user.model.js"
 
 const TEST_EMAIL = `user-routes-test-${Date.now()}@example.com`

package/template/backend/src/domains/user/user.routes.ts

@@ -2,9 +2,9 @@ import { Hono } from "hono"
 import type { Context } from "hono"
 import { zValidator } from "@hono/zod-validator"
 import { UpdateProfileSchema } from "@restack/shared"
-import { requireAuth } from "../../shared/middlewares/require-auth.js"
+import { requireAuth } from "../../infra/middlewares/require-auth.js"
 import { userService, UserNotFoundError } from "./user.service.js"
-import { logger, type AppVariables } from "../../shared/logger/logger.js"
+import { logger, type AppVariables } from "../../utils/logger.js"
 
 /**
  * Routing layer for the User domain.

package/template/backend/src/hono-app.ts

@@ -4,7 +4,7 @@ import { csrf } from "hono/csrf"
 import { logger as honoLogger } from "hono/logger"
 import { requestId } from "hono/request-id"
 import { env } from "./config/env.js"
-import { logger, type AppVariables } from "./shared/logger/logger.js"
+import { logger, type AppVariables } from "./utils/logger.js"
 import { authRoutes } from "./domains/auth/auth.routes.js"
 import { userRoutes } from "./domains/user/user.routes.js"
 

package/template/backend/src/index.ts

@@ -1,6 +1,6 @@
 import { serve } from "@hono/node-server"
 import { env } from "./config/env.js"
-import { logger } from "./shared/logger/logger.js"
+import { logger } from "./utils/logger.js"
 import { app } from "./hono-app.js"
 
 /**

package/template/backend/src/{shared → infra}/middlewares/require-auth.ts

@@ -1,7 +1,7 @@
 import type { MiddlewareHandler } from "hono"
 import { getCookie } from "hono/cookie"
 import { authService } from "../../domains/auth/auth.service.js"
-import type { AppVariables } from "../logger/logger.js"
+import type { AppVariables } from "../../utils/logger.js"
 
 /**
  * Authentication guard middleware.

package/template/backend/src/{shared/logger → utils}/logger.ts

@@ -1,5 +1,5 @@
 import pino from "pino"
-import { env } from "../../config/env.js"
+import { env } from "../config/env.js"
 
 /**
  * Global logger client.
@@ -32,7 +32,7 @@ export const logger = loggerInstance
 
 
 import type { Logger } from "pino"
-import type { AuthTokenPayload } from "../../domains/auth/auth.types.js"
+import type { AuthTokenPayload } from "../domains/auth/auth.types.js"
 
 export type AppVariables = {
   requestId: string

package/template/frontend/app/dashboard/page.tsx

@@ -1,7 +1,7 @@
 import Link from "next/link"
 import { LogoutButton } from "@/domains/auth/components/logout-button"
 import { Button } from "@/components/ui/button"
-import { RequireAuth } from "@/shared/components/require-auth"
+import { RequireAuth } from "@/components/require-auth"
 
 /**
  * Next.js Router Page: Dashboard

package/template/frontend/components.json

@@ -16,7 +16,7 @@
     "utils": "@/lib/utils",
     "ui": "@/components/ui",
     "lib": "@/lib",
-    "hooks": "@/shared/hooks"
+    "hooks": "@/hooks"
   },
   "menuColor": "default",
   "menuAccent": "subtle",

package/template/frontend/domains/auth/hooks/use-login.ts

@@ -1,7 +1,7 @@
 "use client"
 
 import { LoginSchema, type LoginInput } from "@restack/shared"
-import { useAuthMutation } from "@/shared/hooks/use-auth-mutation"
+import { useAuthMutation } from "@/hooks/use-auth-mutation"
 import { authApi } from "../services/auth.api"
 
 /**

package/template/frontend/domains/auth/hooks/use-register.ts

@@ -1,7 +1,7 @@
 "use client"
 
 import { RegisterSchema, type RegisterInput } from "@restack/shared"
-import { useAuthMutation } from "@/shared/hooks/use-auth-mutation"
+import { useAuthMutation } from "@/hooks/use-auth-mutation"
 import { authApi } from "../services/auth.api"
 
 /**

package/template/frontend/domains/auth/services/auth.api.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, LoginInput, RegisterInput } from "@restack/shared"
-import { client, unwrap } from "@/shared/lib/api-client"
+import { client, unwrap } from "@/lib/api-client"
 
 /**
  * Service API layer for the Auth domain.

package/template/frontend/domains/user/services/user.api.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, UpdateProfileInput } from "@restack/shared"
-import { client, unwrap } from "@/shared/lib/api-client"
+import { client, unwrap } from "@/lib/api-client"
 
 /**
  * Service API layer for the User domain.

package/template/frontend/{shared/lib → lib}/api-client.ts

@@ -1,5 +1,5 @@
 import { hc } from "hono/client"
-import type { AppType } from "../../../backend/src/hono-app"
+import type { AppType } from "../../backend/src/hono-app"
 
 const BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001"