Nicholai/Correspondents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Correspondents/docs/bootstrapping.md

2.9 KiB
Raw Blame History

Bootstrapping Checklist

This checklist walks you from cloning the template to having a runnable project with confident defaults. Keep it open while you initialise a new repo.

1. Template hygiene

  • Create a fresh repository (local or Gitea) and copy the template into it.
  • Run ./scripts/bootstrap-template.sh to update the package name, git remotes, and README badges.
  • Remove example images or assets you do not plan to ship (public/, docs/img/, etc.).
  • Delete unused test suites so the CI noise floor stays low.

2. Runtime setup

  • Review .env.example and duplicate it to .env for local development.
  • Fill only the sections that match the integrations you intend to use (auth, storage, calendar, analytics).
  • Create secrets in your chosen manager (doppler, sops, 1Password CLI, environment repository) and document where they live.
  • Configure feature flags or toggles that gate optional modules; default to safe fallbacks.

3. Dependencies & tooling

  • Decide on a package manager (pnpm, npm, yarn) and lock it in the README + CI.
  • Install linting and formatting tools (eslint, prettier, biome, etc.) and wire them into package.json scripts.
  • Add base Git hooks (Husky, Lefthook, or pre-commit) if you rely on pre-push validation.
  • Configure TypeScript paths/aliases so the example tests resolve once you create real modules.

4. Infrastructure & services

  • Document deployment tooling (Wrangler, Vercel, Fly.io, Docker) in docs/stack-decisions.md.
  • Provision staging and production environments or capture the manual steps.
  • Outline database migration flow (Prisma, Drizzle, Kysely) and how to run it locally.
  • For third-party integrations (OAuth, storage, calendar), confirm rate limits and timeout behaviour.

5. CI/CD wiring

  • Choose a pipeline runner (Gitea Actions, Woodpecker, GitHub Actions, etc.).
  • Add jobs for lint, typecheck, unit tests, and build (if applicable).
  • Cache dependencies to keep pipelines fast.
  • Gate deployments on green checks and review status.

6. Documentation & knowledge

  • Update README.md with product-specific copy, screenshots, and deployment commands.
  • Record architectural decisions in docs/stack-decisions.md (lean ADRs are ideal).
  • Extend docs/edge-cases.md with anything unique to this project.
  • Share workflow instructions (branching, PR labels, release cadence) in CONTRIBUTING.md.

7. Launch readiness

  • Smoke-test the bootstrap by running pnpm test (or your equivalent) and ensuring the example specs fail because modules are missing—this keeps you honest.
  • Create a tracking issue or project board with tasks generated from the checklist.
  • Archive or export the checklist with completed items for future reference.

Repeat this ritual for every new project so you ship with fewer unknowns and more confidence.