Nicholai/template-repo
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
template-repo/README.md
Nicholai 06e41023c3 first commit
2025-11-02 01:38:30 -06:00

241 lines
8.9 KiB
Markdown
Raw Blame History

<div align="center">
<!-- DEPLOYMENT COMMAND -->
<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 20px; border-radius: 10px; margin-bottom: 30px;">
<h3 style="color: white; margin: 0;">STARTER COMMAND</h3>
<code style="color: #ffd700; font-size: 16px; font-weight: bold;">./scripts/bootstrap-template.sh</code>
</div>
<a id="readme-top"></a>
<!-- PROJECT SHIELDS -->
[![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]
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://git.biohazardvfx.com/nicholai/template">
<img src="public/template-logo.png" alt="Template Logo" width="400">
</a>
<h1 align="center" style="font-size: 48px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Development Project Template</h1>
<p align="center" style="font-size: 18px; max-width: 680px;">
Opinionated starter kit for new projects deployed through my self-hosted Gitea.<br />
<strong>Documentation-first • Edge-case aware • Automation ready</strong>
<br />
<br />
<a href="#getting-started"><strong>Quick Start »</strong></a>
·
<a href="https://git.biohazardvfx.com/nicholai/template/issues/new?labels=enhancement">Suggest Improvement</a>
</p>
</div>
---
<!-- TABLE OF CONTENTS -->
<details open>
<summary><h2 style="display: inline-block;">Table of Contents</h2></summary>
<ol>
<li><a href="#about-the-template">About The Template</a>
<ul>
<li><a href="#why-this-exists">Why This Exists</a></li>
<li><a href="#core-principles">Core Principles</a></li>
</ul>
</li>
<li><a href="#tech-stack">Tech Stack</a></li>
<li><a href="#architecture">Architecture</a></li>
<li><a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#environment-variables">Environment Variables</a></li>
</ul>
</li>
<li><a href="#development">Development</a>
<ul>
<li><a href="#common-commands">Common Commands</a></li>
<li><a href="#docs--checklists">Docs & Checklists</a></li>
</ul>
</li>
<li><a href="#edge-cases">Edge Cases</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
</ol>
</details>
---
</div>
## About The Template
<div align="center">
<img src="public/template-dashboard.png" alt="Template Dashboard Mock" width="800" style="border-radius: 10px; box-shadow: 0 10px 30px rgba(0,0,0,0.3);">
</div>
<br />
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. |
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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`.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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`.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## Contributing
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branching conventions, commit style, and review expectations.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## License
Use, remix, or extract any portion of this template for your own projects. Attribution is appreciated but not required.
<p align="right"><a href="#readme-top">back to top ↑</a></p>
## 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)
<p align="right"><a href="#readme-top">back to top ↑</a></p>
<!-- MARKDOWN LINKS & IMAGES -->
<!-- shields -->
[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
Reference in New Issue View Git Blame Copy Permalink