Project Template

Full-stack starter: React 18 + Vite 6 frontend, Express.js + SQLite backend, wired together with npm workspaces and pre-configured for AI-assisted development with GitHub Copilot.

What's Included

Tech Stack

Layer	Technology
Frontend	React 18, Vite 6, react-router-dom 6
Backend	Express.js 4, better-sqlite3
Monorepo	npm workspaces + concurrently
Language	ES Modules (JSX frontend, JS backend)
Styling	CSS custom properties (design tokens)

Developer Experience

• npm run dev starts both servers with one command
• Vite proxies /api to Express — no CORS config needed
• Backend auto-reloads via node --watch
• Frontend hot-module replacement via Vite HMR
• npm run seed resets the database with sample data
• VS Code terminal auto-configures Node.js on PATH
• AI agent instructions (.github/copilot-instructions.md + agents.md)

Quick Start

Prerequisites

• Node.js (v18+) installed
• VS Code with GitHub Copilot (recommended)

Setup

# 1. Clone or copy the template
git clone <your-template-repo> my-new-project
cd my-new-project

# 2. Install dependencies
cd app
npm install

# 3. Seed the database
npm run seed

# 4. Start development
npm run dev

Frontend: http://localhost:5173
Backend API: http://localhost:3001/api/health

If npm is not found

Open a new VS Code terminal (the workspace settings auto-configure the PATH for Windows, macOS, and Linux).

Or manually:

• Windows (PowerShell): $env:Path = "$env:ProgramFiles\nodejs;" + $env:Path
• macOS / Linux: export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"

Project Structure

my-project/
├── .github/
│   └── copilot-instructions.md    # Auto-loaded by Copilot every chat
├── .vscode/
│   └── settings.json              # Terminal PATH config
├── agents.md                      # AI agent rules and guardrails
├── start-dev.ps1                  # Helper script (Windows)
├── start-dev.sh                   # Helper script (macOS/Linux)
├── README.md                      # This file
└── app/                           # Monorepo root
    ├── package.json               # Workspaces + concurrently
    ├── backend/
    │   ├── package.json           # Express + better-sqlite3
    │   └── src/
    │       ├── db.js              # Database connection
    │       ├── index.js           # Express server entry point
    │       ├── seed.js            # Database seeder
    │       └── routes/
    │           └── example.js     # Example API route
    └── frontend/
        ├── package.json           # React + Vite
        ├── index.html             # HTML entry point
        ├── vite.config.js         # Vite config with API proxy
        └── src/
            ├── main.jsx           # React entry point
            ├── App.jsx            # Router + layout
            ├── App.css            # App-level styles
            ├── api/
            │   └── index.js       # fetchJSON utility
            ├── components/        # Reusable components
            ├── pages/
            │   ├── HomePage.jsx   # Example page
            │   └── HomePage.css
            └── styles/
                └── tokens.css     # Design tokens (CSS custom properties)

Customising for a New Project

1. Rename — update name fields in all three package.json files
2. Database — edit backend/src/seed.js to define your tables and seed data
3. Routes — add new route files in backend/src/routes/, mount them in index.js
4. Pages — add new pages in frontend/src/pages/, add routes in App.jsx
5. Copilot instructions — update .github/copilot-instructions.md with your schema, routes, and domain context
6. agents.md — update the one-liner path if your workspace root differs

Commands Reference

Command	Run from	What it does
npm run dev	app/	Starts backend + frontend concurrently
npm run seed	app/	Drops and re-creates all tables with sample data
npm run build	app/	Production build of the frontend
npm run start -w backend	app/	Starts backend only (no watch)

Rules for AI Agents

See agents.md for the full list. Key rules:

• Always use npm run dev / npm run seed — never run node directly
• Never use npx node (breaks native modules)
• Kill stale ports before starting servers
• Re-seed after any schema or seed data change
• Don't spawn duplicate servers — HMR handles reloads