create-appystack 0.1.0

package/template/client/src/test/msw/handlers.ts

@@ -0,0 +1,12 @@
+import { http, HttpResponse } from 'msw';
+
+// Wildcard prefix matches any origin — works in both browser (setupWorker)
+// and Node.js (setupServer / Vitest) contexts without needing a hardcoded host.
+export const handlers = [
+  http.get('*/health', () => {
+    return HttpResponse.json({ status: 'ok', timestamp: new Date().toISOString() });
+  }),
+  http.get('*/api/info', () => {
+    return HttpResponse.json({ name: 'AppyStack', version: '1.0.0' });
+  }),
+];

package/template/client/src/test/msw/msw-example.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach, afterAll } from 'vitest';
+import { server } from './server.js';
+import { http, HttpResponse } from 'msw';
+
+// MSW uses its own fetch interception layer (via @mswjs/interceptors).
+// The global setup.ts stubs fetch with vi.fn() for existing tests — those
+// stubs take precedence and are intentional.  In this test file we bypass
+// the stub so we can demonstrate MSW handler interception working correctly.
+//
+// Strategy: save the stub installed by setup.ts, replace it with the real
+// underlying fetch for the duration of each test, then put it back.
+
+// Start/stop MSW for this file only — MSW is opt-in, not global.
+// Global setup.ts stubs fetch with vi.fn() for other tests.
+// Here we unstub to let MSW's interceptors handle real fetch calls.
+beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+let realFetch: typeof fetch;
+
+beforeEach(() => {
+  // Unstub the vi.fn() installed by setup.ts so MSW interceptors work
+  vi.unstubAllGlobals();
+  realFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  // Reinstall the stub so other test files are not affected
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+describe('MSW example — handler interception', () => {
+  it('intercepts GET /health and returns mocked response', async () => {
+    const res = await realFetch('http://localhost/health');
+    const data = (await res.json()) as { status: string; timestamp: string };
+
+    expect(res.ok).toBe(true);
+    expect(data.status).toBe('ok');
+    expect(typeof data.timestamp).toBe('string');
+  });
+
+  it('intercepts GET /api/info and returns mocked response', async () => {
+    const res = await realFetch('http://localhost/api/info');
+    const data = (await res.json()) as { name: string; version: string };
+
+    expect(res.ok).toBe(true);
+    expect(data.name).toBe('AppyStack');
+    expect(data.version).toBe('1.0.0');
+  });
+
+  it('allows runtime handler override with server.use()', async () => {
+    server.use(
+      http.get('*/health', () => {
+        return HttpResponse.json(
+          { status: 'degraded', timestamp: new Date().toISOString() },
+          { status: 503 }
+        );
+      })
+    );
+
+    const res = await realFetch('http://localhost/health');
+    const data = (await res.json()) as { status: string };
+
+    expect(res.status).toBe(503);
+    expect(data.status).toBe('degraded');
+    // setup.ts afterEach calls server.resetHandlers() — restoring defaults for next test
+  });
+});

package/template/client/src/test/msw/server.ts

@@ -0,0 +1,14 @@
+import { setupServer } from 'msw/node';
+import { http, passthrough } from 'msw';
+import { handlers } from './handlers.js';
+
+// Pass socket.io requests through without interception.
+// MSW intercepting WebSocket upgrade requests causes a libuv assertion failure
+// (uv__io_active) when components with live socket.io connections are rendered
+// in tests. Returning passthrough() for all socket.io paths prevents this.
+const socketIoPassthrough = [
+  http.get('*/socket.io/:rest*', () => passthrough()),
+  http.post('*/socket.io/:rest*', () => passthrough()),
+];
+
+export const server = setupServer(...socketIoPassthrough, ...handlers);

package/template/client/src/test/setup.ts

@@ -0,0 +1,10 @@
+import '@testing-library/jest-dom';
+import { vi, beforeEach } from 'vitest';
+
+// Global fetch stub for all tests.
+// Tests that need real fetch interception (e.g. MSW) should call
+// vi.unstubAllGlobals() in their own beforeEach and manage their own
+// MSW server lifecycle — see src/test/msw/msw-example.test.ts for the pattern.
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn());
+});

package/template/client/src/utils/api.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { api, ApiError } from './api.js';
+
+describe('api wrapper', () => {
+  beforeEach(() => {
+    vi.mocked(fetch).mockReset();
+  });
+
+  it('api.get returns parsed JSON on success', async () => {
+    const data = { id: 1, name: 'test' };
+    vi.mocked(fetch).mockResolvedValueOnce(new Response(JSON.stringify(data), { status: 200 }));
+
+    const result = await api.get<typeof data>('/test');
+
+    expect(result).toEqual(data);
+  });
+
+  it('api.get throws ApiError with status on non-ok response', async () => {
+    vi.mocked(fetch).mockResolvedValue(
+      new Response('Not Found', { status: 404, statusText: 'Not Found' })
+    );
+
+    await expect(api.get('/missing')).rejects.toThrow(ApiError);
+    await expect(api.get('/missing')).rejects.toMatchObject({ status: 404, name: 'ApiError' });
+  });
+
+  it('api.post sends correct method, body, and Content-Type header', async () => {
+    const responseData = { created: true };
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify(responseData), { status: 201 })
+    );
+
+    const payload = { name: 'new item' };
+    await api.post('/items', payload);
+
+    expect(fetch).toHaveBeenCalledOnce();
+    const [, options] = vi.mocked(fetch).mock.calls[0];
+    expect(options?.method).toBe('POST');
+    expect(options?.body).toBe(JSON.stringify(payload));
+    expect((options?.headers as Record<string, string>)['Content-Type']).toBe('application/json');
+  });
+
+  it('api.post throws ApiError on 404', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response('Not Found', { status: 404, statusText: 'Not Found' })
+    );
+
+    let caught: unknown;
+    try {
+      await api.post('/missing', { data: 'value' });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(ApiError);
+    expect((caught as ApiError).status).toBe(404);
+    expect((caught as ApiError).name).toBe('ApiError');
+  });
+
+  it('AbortSignal is passed through to fetch', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(new Response(JSON.stringify({}), { status: 200 }));
+
+    const controller = new AbortController();
+    await api.get('/test', controller.signal);
+
+    const [, options] = vi.mocked(fetch).mock.calls[0];
+    expect(options?.signal).toBe(controller.signal);
+  });
+
+  it('AbortSignal is passed through to fetch for post requests', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(new Response(JSON.stringify({}), { status: 200 }));
+
+    const controller = new AbortController();
+    await api.post('/test', { x: 1 }, controller.signal);
+
+    const [, options] = vi.mocked(fetch).mock.calls[0];
+    expect(options?.signal).toBe(controller.signal);
+  });
+});

package/template/client/src/utils/api.ts

@@ -0,0 +1,42 @@
+const BASE_URL = import.meta.env.VITE_API_URL ?? '';
+
+/** Error thrown when an API request receives a non-2xx HTTP response. */
+class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+async function request<T>(
+  path: string,
+  options?: RequestInit & { signal?: AbortSignal }
+): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options);
+  if (!res.ok) {
+    throw new ApiError(res.status, `Request failed: ${res.status} ${res.statusText}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+/**
+ * Typed HTTP request helpers for the AppyStack template.
+ * All methods throw ApiError on non-2xx responses.
+ */
+export const api = {
+  /** Send a GET request and return the parsed JSON response. */
+  get: <T>(path: string, signal?: AbortSignal) => request<T>(path, { signal }),
+  /** Send a POST request with a JSON body and return the parsed JSON response. */
+  post: <T>(path: string, body: unknown, signal?: AbortSignal) =>
+    request<T>(path, {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { 'Content-Type': 'application/json' },
+      signal,
+    }),
+};
+
+export { ApiError };

package/template/client/src/vite-env.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="vite/client" />
+
+// Extend this interface to add type-safe environment variables.
+// Variables must be prefixed with VITE_ to be exposed to the client.
+// Add matching entries to .env.example for documentation.
+interface ImportMetaEnv {
+  readonly VITE_API_URL?: string;
+  readonly VITE_APP_NAME?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/template/client/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "@appydave/appystack-config/typescript/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"],
+      "@hooks/*": ["src/hooks/*"],
+      "@pages/*": ["src/pages/*"],
+      "@utils/*": ["src/utils/*"],
+      "@contexts/*": ["src/contexts/*"],
+      "@config/*": ["src/config/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/template/client/vite.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import path from 'node:path';
+
+// TODO: Update port and proxy target for your project
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+      '@components': path.resolve(__dirname, 'src/components'),
+      '@hooks': path.resolve(__dirname, 'src/hooks'),
+      '@pages': path.resolve(__dirname, 'src/pages'),
+      '@utils': path.resolve(__dirname, 'src/utils'),
+      '@contexts': path.resolve(__dirname, 'src/contexts'),
+      '@config': path.resolve(__dirname, 'src/config'),
+    },
+  },
+  server: {
+    port: 5500,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:5501',
+        changeOrigin: true,
+      },
+      '/health': {
+        target: 'http://localhost:5501',
+        changeOrigin: true,
+      },
+      '/socket.io': {
+        target: 'http://localhost:5501',
+        changeOrigin: true,
+        ws: true,
+      },
+    },
+  },
+});

package/template/client/vitest.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+      '@components': path.resolve(__dirname, 'src/components'),
+      '@hooks': path.resolve(__dirname, 'src/hooks'),
+      '@pages': path.resolve(__dirname, 'src/pages'),
+      '@utils': path.resolve(__dirname, 'src/utils'),
+      '@contexts': path.resolve(__dirname, 'src/contexts'),
+      '@config': path.resolve(__dirname, 'src/config'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/**/*.test.{ts,tsx}', 'src/test/**'],
+      thresholds: {
+        lines: 80,
+        functions: 70,
+        branches: 70,
+        statements: 80,
+      },
+    },
+  },
+});

package/template/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    ports:
+      - '5501:5501'
+    environment:
+      - NODE_ENV=production
+      - PORT=5501
+      # CLIENT_URL is not needed in production — server serves the client directly
+    healthcheck:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:5501/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    restart: unless-stopped

package/template/e2e/smoke.test.ts

@@ -0,0 +1,95 @@
+import { test, expect } from '@playwright/test';
+import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templateRoot = path.resolve(__dirname, '..');
+
+const SERVER_PORT = 5501;
+const CLIENT_PORT = 5500;
+const STARTUP_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 500;
+
+async function waitForUrl(url: string, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return;
+    } catch {
+      // Not ready yet — keep polling
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  throw new Error(`Timed out waiting for ${url} after ${timeoutMs}ms`);
+}
+
+function killProcess(proc: ChildProcess): void {
+  try {
+    if (proc.pid !== undefined) {
+      // Kill the entire process group (catches nodemon child processes)
+      process.kill(-proc.pid, 'SIGTERM');
+    } else {
+      proc.kill('SIGTERM');
+    }
+  } catch {
+    // Process may already be dead — ignore
+  }
+}
+
+let serverProcess: ChildProcess;
+let clientProcess: ChildProcess;
+
+test.beforeAll(async () => {
+  // detached: true creates a new process group so we can kill all children
+  serverProcess = spawn('npm', ['run', 'dev', '-w', 'server'], {
+    cwd: templateRoot,
+    stdio: 'pipe',
+    detached: true,
+    env: { ...process.env, NODE_ENV: 'development' },
+  });
+
+  clientProcess = spawn('npm', ['run', 'dev', '-w', 'client'], {
+    cwd: templateRoot,
+    stdio: 'pipe',
+    detached: true,
+    env: { ...process.env, NODE_ENV: 'development' },
+  });
+
+  // Wait for both servers to be ready before running tests
+  await Promise.all([
+    waitForUrl(`http://localhost:${SERVER_PORT}/health`, STARTUP_TIMEOUT_MS),
+    waitForUrl(`http://localhost:${CLIENT_PORT}`, STARTUP_TIMEOUT_MS),
+  ]);
+});
+
+test.afterAll(async () => {
+  // Use try/finally pattern to ensure both processes are killed even if one throws
+  try {
+    killProcess(serverProcess);
+  } finally {
+    killProcess(clientProcess);
+  }
+});
+
+test('page title contains AppyStack', async ({ page }) => {
+  await page.goto(`http://localhost:${CLIENT_PORT}`);
+  await expect(page).toHaveTitle(/AppyStack/);
+});
+
+test('at least one status card is visible', async ({ page }) => {
+  await page.goto(`http://localhost:${CLIENT_PORT}`);
+  await page.waitForLoadState('networkidle');
+  // The status grid renders cards for server health info
+  const statusGrid = page.locator('[data-testid="status-grid"]');
+  await expect(statusGrid).toBeVisible();
+});
+
+test('/health endpoint returns 200', async () => {
+  const res = await fetch(`http://localhost:${SERVER_PORT}/health`);
+  expect(res.status).toBe(200);
+  const body = (await res.json()) as { status: string };
+  expect(body.status).toBe('ok');
+});

package/template/e2e/socket.test.ts

@@ -0,0 +1,96 @@
+import { test, expect } from '@playwright/test';
+import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templateRoot = path.resolve(__dirname, '..');
+
+const SERVER_PORT = 5501;
+const CLIENT_PORT = 5500;
+const STARTUP_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 500;
+
+async function waitForUrl(url: string, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return;
+    } catch {
+      // Not ready yet — keep polling
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  throw new Error(`Timed out waiting for ${url} after ${timeoutMs}ms`);
+}
+
+function killProcess(proc: ChildProcess): void {
+  try {
+    if (proc.pid !== undefined) {
+      // Kill the entire process group (catches nodemon child processes)
+      process.kill(-proc.pid, 'SIGTERM');
+    } else {
+      proc.kill('SIGTERM');
+    }
+  } catch {
+    // Process may already be dead — ignore
+  }
+}
+
+let serverProcess: ChildProcess;
+let clientProcess: ChildProcess;
+
+test.beforeAll(async () => {
+  // detached: true creates a new process group so we can kill all children
+  serverProcess = spawn('npm', ['run', 'dev', '-w', 'server'], {
+    cwd: templateRoot,
+    stdio: 'pipe',
+    detached: true,
+    env: { ...process.env, NODE_ENV: 'development' },
+  });
+
+  clientProcess = spawn('npm', ['run', 'dev', '-w', 'client'], {
+    cwd: templateRoot,
+    stdio: 'pipe',
+    detached: true,
+    env: { ...process.env, NODE_ENV: 'development' },
+  });
+
+  // Wait for both servers to be ready before running tests
+  await Promise.all([
+    waitForUrl(`http://localhost:${SERVER_PORT}/health`, STARTUP_TIMEOUT_MS),
+    waitForUrl(`http://localhost:${CLIENT_PORT}`, STARTUP_TIMEOUT_MS),
+  ]);
+});
+
+test.afterAll(async () => {
+  // Use try/finally pattern to ensure both processes are killed even if one throws
+  try {
+    killProcess(serverProcess);
+  } finally {
+    killProcess(clientProcess);
+  }
+});
+
+test('socket ping-pong flow sends ping and receives pong response', async ({ page }) => {
+  await page.goto(`http://localhost:${CLIENT_PORT}`);
+  await page.waitForLoadState('networkidle');
+
+  // The Send Ping button is disabled until the socket connects — wait for it to be enabled
+  const sendPingButton = page.getByRole('button', { name: 'Send Ping' });
+  await expect(sendPingButton).toBeVisible();
+  await expect(sendPingButton).toBeEnabled({ timeout: 10_000 });
+
+  // Click Send Ping
+  await sendPingButton.click();
+
+  // Wait for the pong response — the component renders "server:pong received — ..."
+  const pongResponse = page.getByText(/server:pong received/);
+  await expect(pongResponse).toBeVisible({ timeout: 10_000 });
+
+  // The Send Ping button should be available again (not in waiting state)
+  await expect(sendPingButton).toBeVisible();
+  await expect(sendPingButton).toBeEnabled();
+});

package/template/eslint.config.js

@@ -0,0 +1,2 @@
+import appyConfig from '@appydave/appystack-config/eslint/react';
+export default [...appyConfig];

package/template/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@appydave/appystack-template",
+  "version": "0.1.0",
+  "private": true,
+  "description": "RVETS stack boilerplate (React, Vite, Express, TypeScript, Socket.io)",
+  "type": "module",
+  "workspaces": [
+    "shared",
+    "server",
+    "client"
+  ],
+  "scripts": {
+    "dev": "npm run build -w shared && concurrently -n server,client -c blue,green \"npm run dev -w server\" \"npm run dev -w client\"",
+    "build": "npm run build -w shared && npm run build -w server && npm run build -w client",
+    "test": "npm run test -w server -w client",
+    "test:coverage": "npm run test:coverage -w server -w client",
+    "test:e2e": "playwright test",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "npm run typecheck -w shared -w server -w client",
+    "clean": "rm -rf node_modules shared/dist server/dist client/dist",
+    "prepare": "husky",
+    "customize": "tsx scripts/customize.ts"
+  },
+  "devDependencies": {
+    "@appydave/appystack-config": "^1.0.3",
+    "@clack/prompts": "^1.0.1",
+    "@eslint/js": "^9.17.0",
+    "@playwright/test": "^1.58.2",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "concurrently": "^9.1.2",
+    "eslint": "^9.17.0",
+    "eslint-plugin-react": "^7.37.3",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "globals": "^15.14.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,json,css,md}": "prettier --write",
+    "*.{ts,tsx,js}": "eslint --fix"
+  },
+  "author": "David Cruwys",
+  "license": "MIT"
+}

package/template/playwright.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 60_000,
+  fullyParallel: false,
+  retries: 0,
+  workers: 1,
+  reporter: 'list',
+  use: {
+    headless: true,
+    baseURL: 'http://localhost:5500',
+  },
+});