OtakuLeague
An all-in-one anime platform: visualize anime and manga data, track watchlists, and play anime-themed games and quizzes.
Why it exists
To put anime data, tracking and games in one place, and to own a real product end to end, from design to production. It is a solo project built the way a product team would build it: written decisions, tests on every change, CI on every PR (engineering charter).
Today it is in the v1 build: a NestJS API (health, anime data and catalog lists from AniList and MyAnimeList), a Next.js web app with the home page, anime pages and info pages, PostgreSQL, error tracking and CI. See docs/architecture.md.
Run it locally (under 5 minutes)
Prerequisites: git, nvm, Docker (running), and jq for the hook tests.
git clone https://github.com/otakuLeague/otakuleague-core.git
cd otakuleague-core
nvm install # installs and uses Node 24 from .nvmrc (later: nvm use)
npm install -g [email protected] # the version pinned in package.json
pnpm install # all packages; also builds shared-types and sets up git hooks
cp .env.example .env # dev-only placeholder values, no secrets needed
pnpm db:up # PostgreSQL 18 in Docker, waits until healthy
pnpm db:migrate # applies Prisma migrations to the dev database
pnpm dev # API on :3001, web on :3000
Check it works:
Stop with Ctrl+C, then pnpm db:down (keeps the data).
The .env file
.env lives at the repo root only; the API and the web app both read it, and real environment variables win. Restart pnpm dev after editing it.- When
.env.example gains a variable, add it to your .env. If you append from the shell (echo X=1 >> .env), first check that the file ends with a newline: tail -c1 .env | od -c must show \n. Otherwise the new variable is glued to the last line and both values break.
- Sentry is optional: leave
SENTRY_DSN (API) and NEXT_PUBLIC_SENTRY_DSN (web) empty and nothing is sent. Set them to report errors to your own Sentry projects (ADR 0004).
Common problems
- Port 5432 already in use: set
POSTGRES_PORT (e.g. 5433) in .env, change the port in DATABASE_URL and DATABASE_URL_TEST to match, then pnpm db:up.
db:up ends with "container ... is unhealthy", or the logs say the database files are incompatible: an old data volume. pnpm db:reset recreates it (deletes local data).- The API exits at boot with a list of variables:
.env is missing or outdated; compare it with .env.example.
- Start from scratch (stale dependencies or build output):
pnpm clean, then pnpm install. It deletes node_modules, dist, .next and the generated Prisma client, and never .env. Never use git clean -x / -X for this: .env is gitignored, so they delete it too.
Tests
| Command | What it runs | Needs |
|---|
pnpm test | Unit tests: node:test (shared-types), Vitest (api, web), then the hook and scripts/ tests | nothing running |
pnpm test:integration | API *.integration.spec.ts against a real PostgreSQL; recreates and migrates the test database each run | pnpm db:up |
pnpm test:hooks | Claude Code hook and permission tests in .claude/hooks | jq |
pnpm lint / pnpm typecheck | ESLint (zero warnings) / tsc in every package | nothing |
CI runs lint, typecheck, unit tests, integration tests and build on every PR and every push to main.
More
