Official Rocky Linux website — Next.js App Router, React, TypeScript, next-intl, shadcn/ui (Radix), Tailwind.
npm run dev·npm run build·npm run lint·npm run typecheck·npm run test(Jest) ·npm run e2e(Playwright)npm run check:downloads— verify URLs indata/downloads.json- Before committing, run
npm run lint,npm run typecheck, andnpm run testyourself and fix warnings too. The husky pre-commit hook only runs eslint (errors block, warnings don't) and prettier on staged files — it does not typecheck or run tests. predev/prebuild/postinstallclone content from rocky-linux/rockylinux.org-content. SetSKIP_NEWS_FETCH=1when offline.
- Pages:
app/[locale]/<route>/page.tsx; page-only components inapp/[locale]/<route>/components/ - Reusable feature components:
components/orcomponents/<feature>/; UI primitives (shadcn/ui only):components/ui/ - Global types:
types/; ambient declarations:@types/; app-wide hooks:hooks/(create with the first one) - Data:
data/*.json; locale config:config/i18nProperties.ts,i18n/ proxy.tsis Next 16's replacement formiddleware.ts— never create amiddleware.ts- Import alias
@/*→ repo root
Some content lives in rocky-linux/rockylinux.org-content and is cloned in at dev/build time (scripts/fetch-news-content.mjs). The affected paths are listed under the content-repo comment in .gitignore (currently news/ and public/images/content/). Never create or edit files there — they're overwritten on every fetch and never committed. New or changed content (e.g. a news post) goes in a PR to the content repo; only rendering code belongs here.
- All user-facing text via next-intl. Add strings ONLY to
messages/en.json— Crowdin generates the other locales. - Use
Linkand navigation helpers from@/i18n/navigation, nevernext/link. - Pages are server components that compose structure via
children; client state lives in a provider with a custom hook, not in the page. Seedocs/development/pages-and-navigation.mdbefore creating or restructuring a page. - React component props are typed
Readonly<Props>(SonarQube S6759). - Every exported function, component, and hook has a full JSDoc block: summary,
@paramfor each parameter (including destructured props fields),@returns, and@throwswhen it can throw. - Follow WCAG 2.1 AA.
- Write tests for new features and bug fixes.
- IMPORTANT: Never use
any— not as an annotation, cast (as any), or generic argument. Use a real type, a generic,Record<string, unknown>, orunknownwith narrowing. If you believeanyis truly unavoidable, stop and ask the user first with your justification. ESLint enforces this outside__tests__/; the rule applies there too. - Before creating a type, search
types/,@types/, and nearby files for an existing one. - Placement: global/shared →
types/; used by one page only → top of that page file; shared by a few related pages →<route>/types/(prefer promoting totypes/). - Hooks: page/feature hook → its own
useX.tsbeside the components using it; app-wide →hooks/.
- Branch from
developand open PRs againstdevelop(= staging).develop→main(= production) is a release PR.
- Quote bracketed paths in zsh:
git add "app/[locale]/...".
- Index:
docs/README.md - Adding pages, components, header/footer nav, sitemap:
docs/development/pages-and-navigation.md - Composition patterns rationale:
docs/research/react-composition-patterns.md - i18n caching / Vercel locale detection:
docs/i18n/caching-and-locale-detection.md— read before touching locale routing or caching - GitHub Project issues/epics:
docs/project/issue-management.md— read before creating or organizing issues - Disabling downloads:
docs/downloads/disabling-downloads.md - Known build warnings:
docs/known-issues.md
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.