create-blitzpack 0.1.0

package/template/.github/workflows/ci.yml

@@ -0,0 +1,157 @@
+name: CI
+
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+
+# Cancel in-progress runs when a new commit is pushed
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Fast checks that can run in parallel
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run lint
+        run: pnpm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create .env for Prisma
+        run: echo "DATABASE_URL=postgresql://user:pass@localhost:5432/db" > apps/api/.env
+
+      - name: Generate Prisma Client
+        run: pnpm --filter @repo/api db:generate
+
+      - name: Run typecheck
+        run: pnpm run typecheck --filter '!@repo/api' # FIXME: Temporary workaround because of prisma v7 issues
+
+  # Tests and build run after lint/typecheck pass
+  test:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+
+    # PostgreSQL service for integration tests
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: app_dev_test
+          POSTGRES_HOST_AUTH_METHOD: trust
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    env:
+      NODE_ENV: test
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app_dev
+      API_URL: http://localhost:8080
+      FRONTEND_URL: http://localhost:3000
+      PORT: 8080
+      LOG_LEVEL: minimal
+      COOKIE_SECRET: test-cookie-secret-for-ci
+      BETTER_AUTH_SECRET: test-secret-minimum-32-characters-long-for-ci
+      BETTER_AUTH_URL: http://localhost:8080
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma Client
+        run: cd apps/api && npx prisma generate
+
+      - name: Run tests
+        run: pnpm run test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma Client
+        run: pnpm --filter @repo/api db:generate
+
+      - name: Setup Turborepo cache
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: ${{ runner.os }}-turbo-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-turbo-
+
+      - name: Build
+        run: pnpm run build
+        env:
+          NODE_ENV: production
+          API_URL: 'http://localhost:8080'
+          FRONTEND_URL: 'http://localhost:3000'
+          DATABASE_URL: 'postgresql://user:pass@localhost:5432/db'
+          PORT: '8080'
+          LOG_LEVEL: 'minimal'
+          COOKIE_SECRET: 'ci-test-secret-not-for-production'
+          BETTER_AUTH_SECRET: 'ci-test-secret-not-for-production'
+          BETTER_AUTH_URL: 'http://localhost:8080'
+          NEXT_PUBLIC_API_URL: 'http://localhost:8080/api'

package/template/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint-staged

package/template/.husky/pre-push

@@ -0,0 +1 @@
+pnpm typecheck && pnpm test

package/template/.lintstagedrc.cjs

@@ -0,0 +1,4 @@
+module.exports = {
+  '*.{ts,tsx,js,jsx}': ['eslint --fix', 'prettier --write'],
+  '*.{json,md,yml,yaml}': ['prettier --write'],
+};

package/template/.nvmrc

@@ -0,0 +1 @@
+20.0.0

package/template/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

package/template/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.workingDirectories": [{ "mode": "auto" }],
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.preferences.includePackageJsonAutoImports": "on",
+  "typescript.validate.enable": true,
+  "prisma.pinToPrisma6": false
+}

package/template/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+You are a Senior Full-stack Developer and an Expert in TypeScript, Next.js 16, React 19, Fastify, Prisma v7, PostgreSQL, TailwindCSS v5, and shadcn/ui. You are collaborating with a human developer on a production-ready full-stack application.
+
+---
+
+## Critical Requirements & Constraints
+
+### Forbidden Behaviors
+
+- NEVER create markdown files unless the user explicitly asks for it. This is very important
+- NEVER create `index.ts` barrel files. This is a strict requirement
+- AVOID writing comments in code unless absolutely necessary for non-obvious edge cases
+
+### Workflow Requirements
+
+- Make sure you aggressively prefer planning and waiting for user confirmation before writing code for medium to big tasks. This is a strict requirement
+- If you are unsure about anything, ask the user for clarification. This is a strict requirement
+- Prefer using commands or exec scripts (like `pnpm dlx`) for setup related tasks instead of making all the files manually. In case the command requires interactive input, ask the user to do it themselves and provide them with suitable guidance
+
+### Collaboration Principles
+
+- Always be unbiased towards the code, the user's preference and opinions. If you do not agree with the user, make it clear with them. Treat them like a peer
+- Always mention alternative approaches to the user if you think it's necessary
+- Do not be afraid of hurting the user's feelings or making them feel bad about their skills. Having well-written and maintainable code is significantly more important than cozying up to the user
+- Always give a brief and compact summary of all the changes done
+
+---
+
+## Common Commands
+
+### Development Commands
+
+```bash
+pnpm dev
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm test:unit
+pnpm test:integration
+pnpm lint
+```
+
+### Individual Package Commands
+
+```bash
+# Web (Next.js on port 3000)
+cd apps/web
+pnpm dev
+pnpm typecheck
+
+# API (Fastify on port 8080)
+cd apps/api
+pnpm dev
+pnpm start
+```
+
+### Database Commands (run from `apps/api`)
+
+```bash
+pnpm db:generate      # Generate Prisma Client
+pnpm db:migrate       # Create and apply migrations
+pnpm db:push          # Push schema changes (no migration files)
+pnpm db:studio        # Open Prisma Studio UI
+pnpm db:seed          # Seed database
+```
+
+---
+
+## Coding Standards
+
+### Code Style
+
+- Type Definitions: Prefer `interface` for public-facing types and object shapes, `type` for unions, intersections, and computed types
+- Use descriptive variable names with auxiliary verbs (`isLoading`, `hasError`, `canSubmit`)
+- Favor default exports for pages and named exports for utilities or functions
+- **IMPORTANT**: Always use import aliases for files in apps. For packages, use relative imports.
+
+### Error Handling
+
+- Use our custom error classes from `packages/utils/src/errors.ts`
+- Provide user-friendly error messages and avoid leaking implementation details
+
+---
+
+## Project Architecture
+
+### Packages
+
+- All packages (`@repo/packages-types`, `@repo/packages-utils`) are consumed directly as TypeScript source files
+- No build or watch required for these packages
+
+### Environment
+
+- Environment variables are managed per-app with Zod validation
+- Web: Only `NEXT_PUBLIC_*` variables are exposed to the browser
+- Prisma CLI commands are wrapped with `dotenv-cli` to read from `.env.local`
+
+### Database
+
+- The API uses Prisma 7 as the ORM with PostgreSQL
+- Prisma queries are automatically logged based on `LOG_LEVEL`
+
+### Type Safety & Validation
+
+- The codebase emphasizes runtime and compile-time type safety with **Zod v4 as the single validation library** across the entire stack
+- No class-validator
+
+### Testing
+
+Unit Tests: `*.spec.ts`
+Integration Tests: `*.integration.spec.ts`
+
+### Authentication
+
+- Uses Better Auth
+- When creating test users with password auth, set `accountId` to the user's email (not user.id)
+
+---
+
+## Web Architecture Patterns
+
+### State Management
+
+- TanStack Query (React Query): For API calls and data synchronization
+- Jotai: For client-side global state (UI state, user preferences)
+
+### API Integration
+
+- API config centralized in `apps/web/src/lib/api.ts`
+- **API Response Unwrapping**: The `api.ts` fetcher unwraps `{ data: T }` to `T` but preserves `{ data: T[], pagination: {...} }` responses intact
+
+### Authentication & Protected Routes
+
+The web app uses Better Auth for authentication with modern patterns:
+
+- **Auth Client**: Configured in `apps/web/src/lib/auth.ts`
+  - Provides `useSession()` hook for accessing current user/session
+  - Handles sign in/out, session persistence via cookies
+- **Protected Routes**: `<ProtectedRoute>` wrapper component for page-level protection
+
+### UI Component Patterns
+
+- Use Shadcn UI components as base, extend them before creating custom ones
+- Implement thoughtful micro-interactions and hover states wherever needed
+- Use Framer Motion for animations, Lucide React for icons
+- Prefer using `Skeleton` components for loading states instead of spinners (especially for data fetching components)
+- Always create a proper loading state for data fetching components.
+- Always use `cn` helper for class name merging
+- Never write svg code. Always use existing icons from code or Lucide.
+
+---
+
+## API Architecture Patterns
+
+### Fastify Structure
+
+- The Fastify API follows a plugin-based architecture
+- Validation: Zod schemas directly in route definitions via `fastify-type-provider-zod`
+- Dependency Injection: Manual DI via Fastify decorators
+
+### Logging
+
+- The API uses Pino for structured logging with request tracing
+- Verbosity controlled by `LOG_LEVEL` env var: `minimal` | `normal` | `detailed` | `verbose`
+- **IMPORTANT**: Never use `console.log` in the API. Use the logger service instead
+
+**Log Methods:**
+
+- `logger.info(message, context?)` - Standard information
+- `logger.error(message, error?, context?)` - Errors with automatic Error serialization
+- `logger.warn(message, context?)` - Warnings
+- `logger.debug(message, context?)` - Debug information (detailed+ level)
+- `logger.trace(message, context?)` - Trace logs (verbose level only)
+- `logger.perf(message, metrics)` - Performance metrics

package/template/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to Blitzpack
+
+Thank you for your interest in contributing! This is a TypeScript monorepo template designed to help developers ship full-stack applications super fast.
+
+---
+
+## Setup
+
+1. Fork and clone the repository
+2. Run `pnpm install && pnpm init:project`
+3. Start development: `pnpm dev`
+
+## Development
+
+1. Create a feature branch: `git checkout -b feature/your-feature`
+2. Make changes following the code style in `CLAUDE.md`
+3. Run checks: `pnpm typecheck && pnpm lint && pnpm test && pnpm build`
+4. Commit like a sane person
+5. Push and create a Pull request
+
+## Code Style
+
+- Follow patterns in `CLAUDE.md`
+- Always use import aliases (`@/...`)
+
+## Pull Requests
+
+- Rebase on latest main before submitting
+- Ensure all CI checks pass
+- Update documentation if needed
+
+For detailed architecture and patterns, see `CLAUDE.md`.

package/template/Dockerfile

@@ -0,0 +1,90 @@
+# Multi-stage Dockerfile for API deployment
+# Optimized for pnpm monorepo with Prisma
+
+# Stage 1: Dependencies
+FROM node:22-alpine AS deps
+RUN apk add --no-cache libc6-compat openssl
+
+# Install pnpm
+RUN corepack enable && corepack prepare pnpm@9.15.4 --activate
+
+WORKDIR /app
+
+# Copy workspace files
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
+
+# Copy all package.json files for workspace dependencies
+COPY apps/api/package.json apps/api/
+COPY packages/types/package.json packages/types/
+COPY packages/utils/package.json packages/utils/
+
+# Install dependencies (frozen lockfile for reproducible builds)
+RUN pnpm install --frozen-lockfile --prod=false
+
+# Stage 2: Builder
+FROM node:22-alpine AS builder
+RUN apk add --no-cache libc6-compat openssl
+
+RUN corepack enable && corepack prepare pnpm@9.15.4 --activate
+
+WORKDIR /app
+
+# Copy installed dependencies from deps stage
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=deps /app/apps/api/node_modules ./apps/api/node_modules
+COPY --from=deps /app/packages/types/node_modules ./packages/types/node_modules
+COPY --from=deps /app/packages/utils/node_modules ./packages/utils/node_modules
+
+# Copy source code
+COPY . .
+
+# Build shared packages first (types and utils)
+RUN pnpm --filter @repo/packages-types build
+RUN pnpm --filter @repo/packages-utils build
+
+# Generate Prisma Client
+RUN pnpm --filter @repo/api db:generate
+
+# Build the API
+RUN pnpm --filter @repo/api build
+
+# Stage 3: Runner (production)
+FROM node:22-alpine AS runner
+RUN apk add --no-cache openssl
+
+RUN corepack enable && corepack prepare pnpm@9.15.4 --activate
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 fastify
+
+# Copy necessary files from builder
+COPY --from=builder --chown=fastify:nodejs /app/apps/api/dist ./apps/api/dist
+COPY --from=builder --chown=fastify:nodejs /app/apps/api/package.json ./apps/api/
+COPY --from=builder --chown=fastify:nodejs /app/apps/api/prisma ./apps/api/prisma
+COPY --from=builder --chown=fastify:nodejs /app/apps/api/start.sh ./apps/api/
+COPY --from=builder --chown=fastify:nodejs /app/packages ./packages
+COPY --from=builder --chown=fastify:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=fastify:nodejs /app/apps/api/node_modules ./apps/api/node_modules
+COPY --from=builder --chown=fastify:nodejs /app/package.json ./package.json
+COPY --from=builder --chown=fastify:nodejs /app/pnpm-workspace.yaml ./pnpm-workspace.yaml
+
+# Make start script executable
+RUN chmod +x /app/apps/api/start.sh
+
+# Switch to non-root user
+USER fastify
+
+WORKDIR /app/apps/api
+
+# Expose the API port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:8080/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
+
+# Start command (handles database wake-up, runs migrations, then starts server)
+CMD ["/app/apps/api/start.sh"]

package/template/GETTING_STARTED.md

@@ -0,0 +1,35 @@
+# Blitzpack Template Setup
+
+After clicking "Use this template" and cloning your repository:
+
+## Quick Start (Use As-Is)
+
+```bash
+pnpm install
+pnpm init:project
+pnpm dev
+```
+
+**That's it!** The template works out of the box. Customize when ready.
+
+## When You're Ready to Customize
+
+### Update Branding
+
+- `apps/web/src/config/site.ts` → Project name, description, GitHub URL
+- `README.md` → Replace Blitzpack README.md with yours
+
+### Optional: Change Database Credentials
+
+Default credentials: `postgres/postgres_dev_password/app_dev`
+
+To use different credentials:
+
+1. Update `docker-compose.yml` (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB)
+2. Update `apps/api/.env.local` (DATABASE_URL must match step 1)
+3. Restart Docker: `docker compose down && docker compose up -d`
+4. Run migrations: `pnpm --filter @repo/api db:migrate`
+
+---
+
+**Delete this file when done.**

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arman Ganjoo
+
+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/template/README.md

@@ -0,0 +1,116 @@
+<div align="center">
+  <img src="assets/logo.svg" alt="Blitzpack Logo" width="200">
+  <h1>Blitzpack</h1>
+  <p>Full-stack TypeScript monorepo template with Next.js, Fastify, and Turborepo. From zero to production in minutes.</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-≥20.0.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![pnpm](https://img.shields.io/badge/pnpm-≥9.0.0-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![CI](https://github.com/CarboxyDev/blitzpack/actions/workflows/ci.yml/badge.svg)](https://github.com/CarboxyDev/blitzpack/actions/workflows/ci.yml)
+
+</div>
+
+---
+
+## Why Blitzpack?
+
+Stop wasting days bootstrapping your next project. Most templates hand you a skeleton and leave you to figure out database migrations, API documentation, logging infrastructure, and much more. Blitzpack ships with all of it configured and working. You just need to run a single script to get started with a production-ready full-stack application.
+
+**Ship your next project faster with battle-tested infrastructure already wired up.**
+
+- **Zero-config setup**: Run one command and you're ready to code. Environment files, Docker containers, database migrations—all handled automatically.
+
+- **Full-stack type safety**: Zod schemas define your API contracts once in `packages/types`, then flow automatically to web forms, API validation, and database queries. No duplicate validation logic.
+
+- **Production-grade infrastructure**: Better-auth with session management and OAuth ready. Request ID tracing, automatic validation, rate limiting, structured logging, and environment-aware error responses out of the box.
+
+- **AI pair programming ready**: Comprehensive CLAUDE.md file means AI assistants understand your architecture instantly and can accelerate your development.
+
+## Tech Stack
+
+**Web:** Next.js, React, TanStack Query, Tailwind CSS
+
+**Backend:** Fastify, Prisma, PostgreSQL
+
+**Monorepo:** Turborepo, pnpm workspaces
+
+<details>
+<summary>Full stack details</summary>
+
+<p>
+
+**Web**
+
+- Next.js 16 + React 19
+- TanStack Query v5 for server state
+- shadcn/ui + Tailwind CSS v4
+- React Hook Form + Zod validation
+- Jotai for client state
+
+**API**
+
+- Fastify 5
+- Prisma 7 + PostgreSQL 17
+- Better-auth for authentication
+- Pino for logging
+- Scalar API docs
+- Helmet + rate limiting
+
+**Monorepo**
+
+- pnpm workspaces + Turborepo
+- Shared packages for types, utils, config in `packages/`
+- Vitest for testing
+- Husky + lint-staged for pre-commit hooks
+</p>
+</details>
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Automated setup (creates .env files, starts docker, runs migrations)
+pnpm init:project
+
+# Start development
+pnpm dev
+```
+
+The setup script handles everything: environment files, docker containers, database migrations, and optional seeding. Safe to run multiple times.
+
+You must have docker installed and running on your machine.
+
+**What's running:**
+
+- Web: [http://localhost:3000](http://localhost:3000)
+- API: [http://localhost:8080/api](http://localhost:8080/api)
+- API Docs: [http://localhost:8080/docs](http://localhost:8080/docs)
+- Health Check: [http://localhost:8080/health](http://localhost:8080/health)
+
+**Database tools:**
+
+- Prisma Studio: Run `pnpm db:studio` to open [http://localhost:5555](http://localhost:5555) (recommended for data inspection)
+
+**Built-in pages:**
+
+- `/examples` - Component examples
+- `/dashboard` - Protected user dashboard
+- `/login` - Sign in page
+- `/signup` - Create new account
+- `/forgot-password` - Forgot password page
+- `/reset-password` - Reset password page
+
+## Project Structure
+
+```
+blitzpack/
+├── apps/
+│   ├── web/          # Next.js app
+│   └── api/          # Fastify API
+└── packages/
+    ├── types/        # Zod schemas + inferred types
+    └── utils/        # Shared utilities
+```