Tooling & Setup

Everything you need to get a local development environment running and stay productive day-to-day, plus the conventions that govern our CI/CD pipeline and developer experience.

Prerequisites

• Node.js ≥ 20 LTS (managed with nvm or volta)
• npm ≥ 10
• Git ≥ 2.40
• A modern terminal (Windows Terminal, iTerm2, or similar)

Local Setup

1. Clone the repository: git clone https://github.com/km-schmidt/personal-site.git
2. Install dependencies with a clean lockfile install: npm ci
3. Copy the environment template: cp .env.example .env.local and fill in required values. Never commit .env.local.
4. Start the dev server: npm run dev (default http://localhost:3000).

Useful Scripts

• npm run dev — Next.js dev server with Turbopack and hot reload.
• npm run build — production build (type-check + compile).
• npm run start — serve the production build locally.
• npm run lint — ESLint across the project.

Recommended VS Code Extensions

• ESLint
• Prettier — Code formatter
• Tailwind CSS IntelliSense
• GitLens
• Error Lens
• GitHub Pull Requests & Issues

Branching Strategy

Trunk-based development: main is always releasable. Create short-lived branches (feat/..., fix/...), rebase to keep history linear, and merge via squash with a Conventional Commit subject.

CI/CD Pipeline

GitHub Actions runs on every pull request: install → lint → type-check → build → test. Merges to main trigger a deploy to Vercel. Production deploys are gated on a green preview.

Secrets & Configuration

• Store secrets in your platform's secret manager (Vercel / GitHub Actions encrypted secrets).
• Never commit credentials. Pre-commit scanners (gitleaks, trufflehog) run in CI.
• Use distinct credentials per environment (dev, preview, production).

Observability Toolchain

• Structured logging (JSON) with a request-scoped traceId.
• OpenTelemetry SDK for traces and metrics.
• Real-user monitoring via Vercel Analytics or equivalent.