template-repo/README.md

STARTER COMMAND

./scripts/bootstrap-template.sh

Development Project Template

Opinionated starter kit for new projects deployed through my self-hosted Gitea.
Documentation-first • Edge-case aware • Automation ready

Quick Start » · Suggest Improvement

---

Table of Contents

1. About The Template
   • Why This Exists
   • Core Principles
2. Tech Stack
3. Architecture
4. Getting Started
   • Prerequisites
   • Installation
   • Environment Variables
5. Development
   • Common Commands
   • Docs & Checklists
6. Edge Cases
7. Testing
8. Contributing
9. License
10. Contact

---

About The Template

This repository is the baseline I use when starting a new product or service. It keeps the process consistent, reduces the time spent wiring boilerplate, and reminds me to account for the edge cases that usually appear late in a project.

Why This Exists

• Primed documentation: Every project starts with a README, stack decision log, bootstrapping checklist, and edge-case catalogue.
• Automation on day one: scripts/ holds helpers to rename the project, configure remotes, and clean example assets.
• Testing blueprints: Example Vitest suites (__tests__/) demonstrate how to structure API, component, flag, hook, and library tests.
• Gitea ready: Pull request templates, Conventional Commit guidance, and workflows match my self-hosted setup.

Core Principles

Principle	What it means
Documentation-first	Write down intent and constraints before diving into code.
Edge-case aware	Capture the failure scenarios that repeatedly cause incidents.
Reproducible setup	Every project can be re-created from scratch via scripts and docs.
Automation ready	Scripts and CI pipelines are easy to adapt or extend.

back to top ↑

Tech Stack

• Framework: Next.js + TypeScript (adjust as needed)
• Testing: Vitest + Testing Library
• Styling: Tailwind CSS or CSS Modules (pick one per project)
• Database: PostgreSQL (Supabase/Neon friendly)
• Storage: S3-compatible providers (AWS S3, Cloudflare R2)
• Auth: NextAuth.js or custom token flows
• Deployment: Wrangler + Cloudflare Pages/Workers (swap for your platform)

Document any deviations in docs/stack-decisions.md.

back to top ↑

Architecture

flowchart TD
  A[Client] -->|HTTP| B[Next.js App]
  B -->|API Routes| C[(PostgreSQL)]
  B -->|Edge Functions| D[Cloudflare Workers]
  B -->|Auth| E[Identity Provider]
  B -->|Storage SDK| F[(S3/R2 Bucket)]
  D -->|Feature Flags| G[Config Service]

• Keep infrastructure definitions under infra/ once you create them.
• Capture architectural decisions and trade-offs in docs/stack-decisions.md.

back to top ↑

Getting Started

Prerequisites

• Node.js 20+
• pnpm (preferred) or your package manager of choice
• jq (optional, used by bootstrap script)
• Git & access to your Gitea instance

Installation

1. Clone / duplicate the template

   git clone git@git.biohazardvfx.com:nicholai/template.git my-new-project
   cd my-new-project
   

2. Bootstrap

   ./scripts/bootstrap-template.sh
   

3. Install dependencies

   pnpm install
   

4. Follow the checklist
   • Open docs/bootstrapping.md and complete each item.

Environment Variables

Copy .env.example to .env and fill only the sections you need. The file is structured by concern (database, auth, storage, observability) so you can strip unused parts.

back to top ↑

Development

Common Commands

Command	Description
pnpm dev	Start the Next.js dev server.
pnpm lint	Run ESLint / formatting checks.
pnpm test	Execute the Vitest suites.
pnpm build	Generate a production build.

Docs & Checklists

• docs/bootstrapping.md — tasks to run through when spinning up a new project.
• docs/edge-cases.md — prompts for the weird scenarios that usually break things.
• docs/stack-decisions.md — record “why” for each notable tech choice.
• docs/testing-blueprints.md — guidance for adapting the example tests.

back to top ↑

Edge Cases

Edge-case awareness is built into the template:

• Feature flags default to safe behaviour when providers fail.
• Auth, storage, scheduling, and third-party integrations each have dedicated prompts.
• The example tests in __tests__/flags/ and __tests__/lib/ show how to assert defensive behaviour.

Add new lessons learned back into docs/edge-cases.md so the template evolves with every incident.

back to top ↑

Testing

• Tests are organised by domain: api/, components/, hooks/, flags/, lib/.
• Each suite mocks external dependencies and asserts on both happy-path and failure scenarios.
• See docs/testing-blueprints.md for tips on customising them to your project.

back to top ↑

Contributing

See CONTRIBUTING.md for branching conventions, commit style, and review expectations.

back to top ↑

License

Use, remix, or extract any portion of this template for your own projects. Attribution is appreciated but not required.

back to top ↑

Contact

Nicholai — @biohazardvfx — nicholai@biohazardvfx.com

Project Link: https://git.biohazardvfx.com/nicholai/template-repo

back to top ↑