create-appystack 0.1.0

package/template/.dockerignore

@@ -0,0 +1,39 @@
+# Dependencies
+node_modules
+**/node_modules
+
+# Build output
+dist
+**/dist
+
+# Test coverage
+coverage
+**/coverage
+
+# Git
+.git
+.gitignore
+
+# Editor
+.vscode
+.idea
+*.swp
+*.swo
+
+# Environment files (inject at runtime)
+.env
+.env.local
+.env.*.local
+
+# Playwright / E2E
+e2e
+test-results
+playwright-report
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*

package/template/.env.example

@@ -0,0 +1,13 @@
+# Server
+# Runtime environment: development | production | test
+NODE_ENV=development
+# Port the Express server listens on
+PORT=5501
+# Origin the Vite dev server runs on (used for CORS)
+CLIENT_URL=http://localhost:5500
+
+# Client (Vite — prefix VITE_ required)
+# Base URL for API requests. Leave empty to use the Vite dev proxy.
+VITE_API_URL=
+# Application display name shown in the UI
+VITE_APP_NAME=AppyStack

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

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Format check
+        run: npm run format:check
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test

package/template/.husky/pre-commit

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

package/template/.prettierignore

@@ -0,0 +1,7 @@
+dist
+build
+node_modules
+coverage
+package-lock.json
+test-results
+playwright-report

package/template/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "arrowParens": "always"
+}

package/template/.vscode/launch.json

@@ -0,0 +1,59 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Server",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["${workspaceFolder}/server/src/index.ts"],
+      "cwd": "${workspaceFolder}/server",
+      "env": {
+        "NODE_ENV": "development",
+        "PORT": "5501",
+        "CLIENT_URL": "http://localhost:5500"
+      },
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/server/dist/**/*.js"],
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "name": "Attach to Server",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "restart": true,
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/server/dist/**/*.js"],
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "name": "Debug Client",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:5500",
+      "webRoot": "${workspaceFolder}/client/src",
+      "sourceMaps": true,
+      "sourceMapPathOverrides": {
+        "webpack:///./src/*": "${webRoot}/*"
+      }
+    },
+    {
+      "name": "Debug Current Test",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/vitest",
+      "args": ["run", "${relativeFile}"],
+      "cwd": "${workspaceFolder}",
+      "sourceMaps": true,
+      "skipFiles": ["<node_internals>/**"],
+      "smartStep": true
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Full Stack",
+      "configurations": ["Debug Server", "Debug Client"]
+    }
+  ]
+}

package/template/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+AI agent context for the AppyStack template project.
+
+## What Is This?
+
+A RVETS stack boilerplate (React, Vite, Express, TypeScript, Socket.io) structured as an npm workspaces monorepo with three packages: client, server, and shared.
+
+## Architecture
+
+```
+client (React 19 + Vite 7 + TailwindCSS v4)  →  port 5500
+  ↕ proxy (/api, /health, /socket.io)
+server (Express 5 + Socket.io + Pino + Zod)   →  port 5501
+  ↕ imports
+shared (TypeScript interfaces only)
+```
+
+## Commands
+
+```bash
+npm run dev           # Start both client + server (concurrently)
+npm run build         # Build shared → server → client
+npm test              # Run server + client tests
+npm run lint          # ESLint 9 flat config
+npm run format:check  # Prettier check
+npm run typecheck     # TypeScript across all workspaces
+```
+
+## Key Files
+
+- `server/src/config/env.ts` — Zod-validated environment config
+- `server/src/index.ts` — Express app + Socket.io + graceful shutdown
+- `client/src/pages/LandingPage.tsx` — Clean starting page with ASCII banner (replace TODO content with your app)
+- `client/src/demo/DemoPage.tsx` — Template feature showcase (delete when building your app)
+- `client/src/demo/StatusGrid.tsx` — Demo: server health status cards (in demo/, delete when done)
+- `client/src/demo/TechStackDisplay.tsx` — Demo: tech stack listing (in demo/, delete when done)
+- `client/src/demo/SocketDemo.tsx` — Demo: Socket.io ping/pong (in demo/, delete when done)
+- `client/src/hooks/useServerStatus.ts` — Fetches /health and /api/info
+- `client/src/hooks/useSocket.ts` — Socket.io connection hook
+- `shared/src/types.ts` — All shared TypeScript interfaces
+- `client/vite.config.ts` — Dev proxy config (routes /api, /health, /socket.io to server)
+
+## Patterns
+
+- **Shared types**: Define in `shared/src/types.ts`, import via `@appystack-template/shared`
+- **API routes**: Add to `server/src/routes/`, mount in `server/src/index.ts`
+- **Socket events**: Add to `ServerToClientEvents` / `ClientToServerEvents` in shared, handle in `server/src/index.ts`
+- **Components**: Place in `client/src/components/`, pages in `client/src/pages/`
+- **Demo components**: Live in `client/src/demo/` — delete the entire folder when starting your app
+  - The `demo/` folder (StatusGrid, TechStackDisplay, SocketDemo, ContactForm) is intentionally untested
+  - It is scaffolding designed to be deleted when building a real app
+  - Tests for demo/ components would be maintenance debt on throwaway code
+  - When you delete `demo/`, delete any test files associated with it
+- **Styling**: TailwindCSS v4 with CSS variables in `client/src/styles/index.css`
+- **Environment**: Extend Zod schema in `server/src/config/env.ts`
+
+## Customization TODO Markers
+
+Search for `TODO` to find all customization points:
+
+- Project name and package scopes
+- Port numbers (5500/5501)
+- ASCII banner branding
+- Shared type interfaces
+- ESLint config (now imports from `@appydave/appystack-config/eslint/react` — already done)
+
+## Testing
+
+- **Server**: Vitest + Supertest (`server/src/test/`)
+- **Client**: Vitest + Testing Library + jsdom (`client/src/test/`)
+- Mocks: Client tests mock `useServerStatus` and `useSocket` hooks
+
+## Config Inheritance
+
+ESLint config imports from `@appydave/appystack-config/eslint/react` (3-line config — migration complete as of Wave 2).
+
+TypeScript configs extend from `@appydave/appystack-config/typescript/{base,node,react}`.
+
+## For Consumer Apps (After Customizing This Template)
+
+This CLAUDE.md describes the template as-shipped. Once you've built on top of it, update this section so AI coding agents understand your specific setup.
+
+### Database (update if applicable)
+
+- ORM/driver: \***\*\_\_\_\*\***
+- Schema location: \***\*\_\_\_\*\***
+- Migration command: \***\*\_\_\_\*\***
+- Test strategy: \***\*\_\_\_\*\***
+
+### Authentication (update if applicable)
+
+- Approach: \***\*\_\_\_\*\***
+- Token storage: \***\*\_\_\_\*\***
+- Protected route middleware: \***\*\_\_\_\*\***
+- Socket.io auth: \***\*\_\_\_\*\***
+
+### State Management (update if applicable)
+
+- Library: \***\*\_\_\_\*\***
+- Store location: \***\*\_\_\_\*\***
+- Key patterns: \***\*\_\_\_\*\***
+
+### Custom Middleware (update if applicable)
+
+List any middleware added beyond the defaults (helmet, compression, cors, requestLogger, rateLimiter, errorHandler):
+
+- ***
+
+### Additional Environment Variables
+
+Document any env vars added beyond NODE_ENV, PORT, CLIENT_URL, VITE_API_URL, VITE_APP_NAME:
+
+- ***

package/template/Dockerfile

@@ -0,0 +1,56 @@
+# syntax=docker/dockerfile:1
+
+# ── Build stage ───────────────────────────────────────────────────────────────
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files for all workspaces
+COPY package.json package-lock.json ./
+COPY shared/package.json ./shared/
+COPY server/package.json ./server/
+COPY client/package.json ./client/
+
+# Install all dependencies (including devDependencies needed for build)
+RUN npm ci
+
+# Copy source files
+COPY shared/ ./shared/
+COPY server/ ./server/
+COPY client/ ./client/
+COPY eslint.config.js ./
+COPY .prettierrc .prettierignore ./
+
+# Build: shared → server → client
+RUN npm run build
+
+# ── Production stage ──────────────────────────────────────────────────────────
+FROM node:20-alpine AS production
+
+ENV NODE_ENV=production
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json ./
+COPY shared/package.json ./shared/
+COPY server/package.json ./server/
+COPY client/package.json ./client/
+
+# Install production dependencies only
+RUN npm ci --omit=dev
+
+# Copy built artifacts from builder
+COPY --from=builder /app/shared/dist ./shared/dist
+COPY --from=builder /app/server/dist ./server/dist
+COPY --from=builder /app/client/dist ./client/dist
+
+# Copy .env.example for reference (actual env comes from runtime)
+COPY .env.example ./
+
+EXPOSE 5501
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:5501/health || exit 1
+
+CMD ["node", "server/dist/index.js"]

package/template/README.md

@@ -0,0 +1,219 @@
+# [App Name]
+
+> One line describing what this app is. Replace this.
+
+Built on the [AppyStack](https://github.com/appydave/appystack) RVETS template — React, Vite, Express, TypeScript, Socket.io.
+
+---
+
+## Stack
+
+| Layer      | Technology                   | Role in this project                                                                 |
+| ---------- | ---------------------------- | ------------------------------------------------------------------------------------ |
+| Client     | React 19 + Vite 7            | UI — served from port 5500 in dev, proxies `/api`, `/health`, `/socket.io` to server |
+| Server     | Express 5 + Socket.io        | REST API + real-time events on port 5501                                             |
+| Shared     | TypeScript only              | Interfaces that both client and server import — no runtime code                      |
+| Styling    | TailwindCSS v4               | Utility classes, CSS variables in `client/src/styles/index.css`                      |
+| Validation | Zod                          | Server env vars + request body schemas                                               |
+| Logging    | Pino + pino-http             | Structured JSON logs, request tracing with UUID                                      |
+| Quality    | Vitest + ESLint 9 + Prettier | Tests, linting, formatting across all workspaces                                     |
+
+---
+
+## Quick Start
+
+```bash
+npm install
+cp .env.example .env
+npm run dev
+# Client: http://localhost:5500
+# Server: http://localhost:5501
+```
+
+Both processes start concurrently. The client dev server proxies all `/api`, `/health`, and `/socket.io` requests to the Express server — no CORS configuration needed in development.
+
+---
+
+## What's In Here
+
+### `client/` — React app (port 5500)
+
+**Demo components** (`client/src/demo/`) — delete this entire folder when starting your app:
+
+| Component          | What it does                                                     |
+| ------------------ | ---------------------------------------------------------------- |
+| `StatusGrid`       | Displays server health + info fetched on load                    |
+| `TechStackDisplay` | Lists the tech stack — replace or delete for your app            |
+| `SocketDemo`       | Live ping/pong demo via Socket.io — shows real-time wiring works |
+| `ContactForm`      | Example form with React Hook Form + Zod validation               |
+
+**Components** (`client/src/components/`):
+
+| Component       | What it does               |
+| --------------- | -------------------------- |
+| `ErrorFallback` | Error boundary fallback UI |
+
+**Hooks** (`client/src/hooks/`):
+
+| Hook              | What it does                                                     |
+| ----------------- | ---------------------------------------------------------------- |
+| `useServerStatus` | Fetches `/health` and `/api/info` on mount, returns status state |
+| `useSocket`       | Manages Socket.io connection lifecycle, exposes connection state |
+
+**Pages** (`client/src/pages/`):
+
+- `LandingPage.tsx` — The default landing page with ASCII banner and status grid. Replace the banner and content for your app.
+
+**Vite config** (`client/vite.config.ts`):
+
+Dev proxy routes `/api`, `/health`, and `/socket.io` to `http://localhost:5501`. Update target if you change the server port.
+
+---
+
+### `server/` — Express API (port 5501)
+
+**Routes** (`server/src/routes/`):
+
+| Route           | What it does                                    |
+| --------------- | ----------------------------------------------- |
+| `GET /health`   | Returns `{ status: "ok", timestamp }`           |
+| `GET /api/info` | Returns Node version, environment, port, uptime |
+
+**Middleware** (`server/src/middleware/`):
+
+| Middleware      | What it does                                                |
+| --------------- | ----------------------------------------------------------- |
+| `requestLogger` | Pino-http request logging with UUID per request             |
+| `errorHandler`  | Central error handler — catches thrown errors, returns JSON |
+| `rateLimiter`   | Express rate-limit — 100 requests per 15 minutes per IP     |
+| `validate`      | Zod request body validation factory                         |
+
+**Config** (`server/src/config/`):
+
+- `env.ts` — Zod-validated environment variables. Add new vars here; they'll be type-safe everywhere.
+- `logger.ts` — Pino logger instance. Import this rather than using `console` in server code.
+
+**Socket.io events** (wired in `server/src/index.ts`):
+
+| Event            | Direction       | What it does                        |
+| ---------------- | --------------- | ----------------------------------- |
+| `client:ping`    | Client → Server | Ping                                |
+| `server:message` | Server → Client | Response with message and timestamp |
+
+---
+
+### `shared/` — TypeScript interfaces
+
+`shared/src/types.ts` holds all interfaces used by both client and server:
+
+- `ApiResponse<T>` — wrapper for all API responses
+- `HealthResponse` — shape of `/health`
+- `ServerInfo` — shape of `/api/info`
+- `SocketEvents` — `ServerToClientEvents` + `ClientToServerEvents`
+
+Import in client or server:
+
+```typescript
+import type { ApiResponse, SocketEvents } from '@appystack-template/shared';
+```
+
+---
+
+## Customisation
+
+Run the interactive setup script first:
+
+```bash
+npm run customize
+```
+
+That handles renaming package scopes and setting ports. Then work through this checklist:
+
+- [ ] Rename packages in `package.json`, `client/package.json`, `server/package.json`, `shared/package.json` — change `@appystack-template/*` to `@your-app/*`
+- [ ] Update ports if 5500/5501 are taken — change `client/vite.config.ts`, `.env`, and `server/src/config/env.ts`
+- [ ] Replace the ASCII banner in `client/src/pages/LandingPage.tsx`
+- [ ] Define your domain types in `shared/src/types.ts` — replace or extend `ServerInfo` / `SocketEvents`
+- [ ] Add your first API route in `server/src/routes/`, mount it in `server/src/index.ts`
+- [ ] Add your first Socket.io event to `ClientToServerEvents` / `ServerToClientEvents` in shared, then handle in `server/src/index.ts`
+- [ ] Delete or repurpose `TechStackDisplay` and `SocketDemo` once you have real content
+- [ ] Add your environment variables to `.env.example` and the Zod schema in `server/src/config/env.ts`
+
+Search for `TODO` across the codebase to find every customisation point:
+
+```bash
+grep -r "TODO" --include="*.ts" --include="*.tsx" --include="*.json" .
+```
+
+---
+
+## Port Configuration
+
+| Service          | Port | Config location                    |
+| ---------------- | ---- | ---------------------------------- |
+| Client (Vite)    | 5500 | `client/vite.config.ts`            |
+| Server (Express) | 5501 | `.env`, `server/src/config/env.ts` |
+
+The client proxies `/api`, `/health`, and `/socket.io` to the server during development. No CORS config needed in dev.
+
+---
+
+## Scripts
+
+| Script                  | What it does                                     |
+| ----------------------- | ------------------------------------------------ |
+| `npm run dev`           | Start client + server concurrently               |
+| `npm run build`         | Build shared → server → client                   |
+| `npm test`              | Run all tests (server + client)                  |
+| `npm run test:coverage` | Run tests with coverage report                   |
+| `npm run lint`          | ESLint across all workspaces                     |
+| `npm run lint:fix`      | ESLint with auto-fix                             |
+| `npm run format`        | Prettier — write all files                       |
+| `npm run format:check`  | Prettier — check only                            |
+| `npm run typecheck`     | TypeScript check across all workspaces           |
+| `npm run clean`         | Remove all `node_modules` and `dist` directories |
+| `npm run customize`     | Interactive rename + port setup script           |
+
+---
+
+## Adding Things
+
+### New API route
+
+1. Create `server/src/routes/your-route.ts`
+2. Mount it in `server/src/index.ts`: `app.use('/api/your-route', yourRouter)`
+3. Add the response type to `shared/src/types.ts` if the client needs it
+
+### New Socket.io event
+
+1. Add to `ClientToServerEvents` or `ServerToClientEvents` in `shared/src/types.ts`
+2. Handle the event in `server/src/index.ts` inside the `io.on('connection', ...)` block
+3. Emit from the client via the `useSocket` hook
+
+### New environment variable
+
+1. Add to `.env` and `.env.example`
+2. Add to the Zod schema in `server/src/config/env.ts`
+3. Export from the `env` object — it will be type-safe everywhere it's imported
+
+### New shared type
+
+1. Add to `shared/src/types.ts`
+2. Re-export from `shared/src/index.ts` if not already exported
+3. Import in client or server: `import type { YourType } from '@appystack-template/shared'`
+
+---
+
+## Docs
+
+AppyStack patterns and decisions are documented in the AppyStack repo:
+
+| Guide                                         | What's in it                                           |
+| --------------------------------------------- | ------------------------------------------------------ |
+| [Testing guide](../docs/testing-guide.md)     | Vitest patterns, MSW setup, hook testing, socket mocks |
+| [Socket.io guide](../docs/socket-io.md)       | Event patterns, auth, rooms, typed events              |
+| [API design](../docs/api-design.md)           | Route conventions, error handling, validation patterns |
+| [Architecture](../docs/architecture.md)       | Full stack decisions, pitfalls, npm publishing         |
+| [Environment](../docs/environment.md)         | Env var setup, Zod schema patterns                     |
+| [Troubleshooting](../docs/troubleshooting.md) | Common problems and fixes                              |
+
+> These links are relative to the AppyStack repo. If you copied the template without the docs, find them at https://github.com/appydave/appystack/tree/main/docs

package/template/client/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- TODO: Update title for your project -->
+    <title>AppyStack Template</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/client/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@appystack-template/client",
+  "version": "0.1.0",
+  "private": true,
+  "description": "React + Vite client for AppyStack template",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@appystack-template/shared": "*",
+    "clsx": "^2.1.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-error-boundary": "^6.1.1",
+    "react-hook-form": "^7.71.2",
+    "socket.io-client": "^4.8.1",
+    "tailwind-merge": "^2.6.0",
+    "@hookform/resolvers": "^5.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^26.1.0",
+    "msw": "^2.12.10",
+    "tailwindcss": "^4.1.18",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  }
+}