AGENTS.md — Polaris Task Force

What this is

Next.js 16 + Payload CMS 3.68.5 app for an Arma 3 unit. PostgreSQL database via @payloadcms/db-postgres + Drizzle. Tailwind CSS v4 (no config file — CSS-based). shadcn/ui (new-york style, lucide icons). Dark-themed frontend.

Package manager

Bun is the primary package manager (bun.lock, bunfig.toml). pnpm-lock.yaml also exists; use Bun for installs and running scripts.

Essential commands

bun install               # install deps
bun run dev               # dev server (webpack, localhost:3000)
bun run devsafe           # clears .next cache then dev
bun run build             # production build (--max-old-space-size=8000, webpack)
bun run lint              # ESLint (next/core-web-vitals + next/typescript)
bun run test              # runs test:int then test:e2e sequentially
bun run test:int          # vitest integration tests only
bun run test:e2e          # playwright e2e tests only
bun run db                # drizzle-kit wrapper (e.g. bun run db migrate)
bun run generate:types    # regenerates payload-types.ts
bun run generate:importmap # regenerates payload admin importMap

Type checking / linting order

bun run lint runs ESLint. There is no separate typecheck script — TypeScript errors surface during bun run lint and bun run build.

Test details

Integration tests: tests/int/**/*.int.spec.ts — Vitest with jsdom. Requires a live PostgreSQL database (connection from .env). Uses dotenv/config via vitest.setup.ts.
E2E tests: tests/e2e/*.e2e.spec.ts — Playwright (Chromium only). Auto-starts bun run dev via webServer config. Currently minimal (homepage smoke test).
Run a single integration test: bun run vitest run tests/int/api.int.spec.ts
Run a single e2e test: bun run playwright test tests/e2e/frontend.e2e.spec.ts

Generated files — never edit manually

src/payload-types.ts — regenerated by bun run generate:types
src/payload-generated-schema.ts — regenerated by Payload db-schema generation
src/app/(payload)/admin/importMap.js — regenerated by bun run generate:importmap
src/app/(payload)/layout.tsx — auto-generated by Payload

Path aliases

@/* → ./src/*
@payload-config → ./src/payload.config.ts

App structure

src/app/(frontend)/ — public-facing pages (dashboard, logistics, home). Layout has sidebar + auth check.
src/app/(payload)/ — Payload admin panel and API routes. Auto-generated layout.
src/app/my-route/ — example custom API route.

Collections (Payload CMS)

Organized by domain under src/collections/:

users/ — Users (auth, username login), Ranks, Profiles, Awards, Qualifications, Assignments, Experience
intelligence/ — Missions, Campaigns, Factions, Technologies
logistics/ — Assets, Resources, Vehicles, Structures
world/ — Maps, NarrativeEvents
server/ — MissionFiles, ModLists
game/ — GameRules (global), GameStructures, GameHardResources

Access control helpers live in src/utils/access-control/ (isRole, hasRoles). Roles: guest, user, admin, developer.

Auth

Username-based login (no email login). Users log in via Payload admin with username only.

Database

PostgreSQL via @payloadcms/db-postgres. Schema defined in src/payload-generated-schema.ts. Migrations in src/migrations/ (timestamp-named .ts + .json pairs, registered in migrations/index.ts). Drizzle config reads DATABASE_URI from env.

In development, postgresAdapter uses push: true to auto-sync schema.

Code style

Prettier: double quotes, trailing commas (all), 100 char print width, semicolons.
ESLint: next/core-web-vitals + next/typescript. @typescript-eslint/no-unused-vars warns (prefix unused with _).
Tailwind v4: no tailwind.config — configured via @tailwindcss/postcss in postcss.config.mjs and CSS imports. Use cn() from @/lib/utils for class merging.

UI components

shadcn/ui components live in src/components/ui/. Use bunx shadcn@latest add <component> to add new ones. Frontend components in src/components/frontend/. Payload admin custom components referenced in payload.config.ts under admin.components.

Environment

.env — local dev (PostgreSQL connection string + PAYLOAD_SECRET)
.env.example — template (still shows MongoDB URI — outdated, the app uses PostgreSQL)
.env.test — test/staging database
test.env — NODE_OPTIONS for playwright (loaded by playwright config)

Deploy

bun run deploy bumps patch version (via bun pm version patch), builds, then runs build/deploy.sh. The build/ directory is gitignored so the deploy script is not in the repo.

Gotchas

.env.example shows MongoDB URI but the app uses PostgreSQL — trust DATABASE_URI format in .env.test as the real reference.
bun run build passes --max-old-space-size=8000 — the build is memory-intensive.
The devturbo script uses Turbopack; dev and devsafe use webpack. These are different bundlers with different behavior.
Playwright tests auto-start the dev server — make sure port 3000 is free before running e2e.
Payload admin layout and importMap are auto-generated — do not edit by hand.
.npmrc sets legacy-peer-deps=true for dependency resolution compatibility.

5.3 KiB Raw Blame History