STARTER COMMAND

./scripts/bootstrap-template.sh
[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![LinkedIn][linkedin-shield]][linkedin-url]
Template Logo

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
  2. Tech Stack
  3. Architecture
  4. Getting Started
  5. Development
  6. Edge Cases
  7. Testing
  8. Contributing
  9. License
  10. Contact
---
## About The Template
Template Dashboard Mock

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 ```mermaid 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** ```bash git clone git@git.biohazardvfx.com:nicholai/template.git my-new-project cd my-new-project ``` 2. **Bootstrap** ```bash ./scripts/bootstrap-template.sh ``` 3. **Install dependencies** ```bash 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`](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](https://linkedin.com/in/biohazardvfx) — nicholai@biohazardvfx.com Project Link: [https://git.biohazardvfx.com/nicholai/template-repo](https://git.biohazardvfx.com/nicholai/template-repo)

back to top ↑

[contributors-shield]: https://img.shields.io/gitea/contributors/nicholai/template?style=for-the-badge [contributors-url]: https://git.biohazardvfx.com/nicholai/template/graphs/contributors [forks-shield]: https://img.shields.io/gitea/forks/nicholai/template?style=for-the-badge [forks-url]: https://git.biohazardvfx.com/nicholai/template/network/members [stars-shield]: https://img.shields.io/gitea/stars/nicholai/template?style=for-the-badge [stars-url]: https://git.biohazardvfx.com/nicholai/template/stars [issues-shield]: https://img.shields.io/gitea/issues/nicholai/template?style=for-the-badge [issues-url]: https://git.biohazardvfx.com/nicholai/template/issues [linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 [linkedin-url]: https://linkedin.com/in/biohazardvfx