Skip to content

docs: improve dev onboarding experience#285

Merged
brh28 merged 2 commits intomainfrom
docs/improve-dev-onboarding
Feb 24, 2026
Merged

docs: improve dev onboarding experience#285
brh28 merged 2 commits intomainfrom
docs/improve-dev-onboarding

Conversation

@forge0x
Copy link
Contributor

@forge0x forge0x commented Feb 24, 2026

What

Improves the developer onboarding experience for new contributors setting up the Flash backend locally.

Changes

1. DEV.md — Complete rewrite

  • Quick Start section (3 commands to running server)
  • Prerequisites table with exact versions and install links
  • Step-by-step manual setup with copy-pasteable commands
  • Architecture diagram showing all services and ports
  • Troubleshooting section covering the most common issues:
    • UnauthorizedError (use oathkeeper proxy, not direct port)
    • Node engine incompatibility
    • Docker variable warnings
    • SendGrid API key warning
  • Useful commands reference table

2. dev/setup.sh — New interactive setup script

  • Validates Node.js version (auto-switches via nvm if available)
  • Checks yarn, Docker, direnv
  • Prompts for Ibex sandbox credentials and writes .env.local
  • Generates dev-overrides.yaml automatically
  • Installs dependencies
  • Starts Docker containers
  • Prints success summary with next steps

3. package.json — Fix engine spec

  • Changed "node": "20""node": ">=20.18.1 <21"
  • The cheerio@1.1.2 dependency requires >=20.18.1, so 20.10.0 fails on yarn install
  • The bare "20" spec was too loose — it matched Node 20.10.0 which then broke on transitive deps

Issues Found During Setup

  1. Node version: "node": "20" in package.json matches any 20.x, but cheerio needs >=20.18.1 → confusing error for devs using 20.10.0
  2. No quick start: DEV.md assumed familiarity with direnv, config structure, and credential flow
  3. No troubleshooting: Common errors (auth error on direct port, SendGrid warning) had no documentation
  4. Manual credential setup: Required reading multiple files to understand where credentials go

Testing

  • Cloned fresh, ran ./dev/setup.sh, then make start — server started and responded on all endpoints
  • Verified GraphQL queries work through oathkeeper proxy at localhost:4002

- Rewrite DEV.md with clearer quick-start, architecture overview,
  troubleshooting section, and useful commands reference
- Add dev/setup.sh — interactive script that validates prerequisites,
  configures Ibex credentials, installs deps, and starts Docker
- Fix package.json engine spec: '20' → '>=20.18.1 <21' (cheerio
  requires >=20.18.1, bare '20' matched 20.10.0 which fails)
- Add troubleshooting entry for price service amd64 platform warning on ARM Macs
- Add IBEX_URL, IBEX_EMAIL, IBEX_PASSWORD defaults to .env to suppress
  docker compose warnings about unset variables
@brh28 brh28 merged commit 1fcd462 into main Feb 24, 2026
@brh28 brh28 deleted the docs/improve-dev-onboarding branch February 24, 2026 16:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants