Code Style

The repo's CLAUDE.md and .ai-rules-universal.md are the longer canonical references. This page covers the everyday rules.

TypeScript#

No any. If you absolutely must, use unknown and narrow, or document why with a comment. Pre-existing any is gradually being replaced.
No // @ts-ignore without a comment explaining the underlying type bug + how to remove it.
Strict mode is on in every tsconfig.json. Don't loosen it.
Prefer type for unions/intersections, interface for object shapes.
Re-export types with import type + export type so they tree-shake cleanly.

Sorted into groups by eslint-plugin-import rules:

Blank line between groups. The autofix handles it: pnpm run lint:fix.

kebab-case for files: lib/auth/email-allowlist.ts, apps/workspace/app/(workspace)/sales/page.tsx.
React components in PascalCase.tsx: components/ui/Button.tsx.
Test files: <file>.test.ts next to source, or __tests__/ for shared fixtures.

Prefer createApiHandler (lib/api/wrapper.ts) for new and refactored API routes. It wraps the handler with uniform exception→status mapping, request logging, rate-limiting and CORS, so the handler just gates with checkRole, validates with validateInput, throws typed exceptions, and returns the happy path. The CPT routes (industries / use-cases / videos) are the reference shape. Many older routes still hand-roll try/catch — migrate them to the wrapper when you touch them.
Throw custom exceptions from @matters/lib/errors/exceptions (NotFoundError, ForbiddenError, ValidationError, ExternalServiceError, …), not raw Error. The wrapper / handleApiError maps each to the correct status code.
If you must hand-roll: logger.error(...) first, then return a typed response — don't let exceptions bubble to Next.js's default handler.
Never include error.message in 4xx/5xx responses unless you're 100% sure it's safe to expose. Most aren't.

Use logger from @/lib/errors/logger. Not console.log.
Production drops debug. Use info for "expected milestone happened", warn for "unexpected but recoverable", error for "actual failure that needs Sentry attention".
Context is structured: logger.info("Webinar published", { webinarId, slug }), not logger.info("Webinar published: " + webinarId).

Inside API handlers: const { userId } = await auth(); for the userId, await checkRole(...) for permission gates.
Inside React Server Components: await currentUser() and await requirePermission(...) from lib/auth/guards.ts.
Never invent your own auth check. Always go through these.

Every mutation handler validates the request body with Zod before any side-effect. Failures return 400 with { error, issues: parsed.error.issues }.
Reusable schemas live in lib/utils/validation.ts (emailSchema, urlSchema, etc.).
Don't validate twice. If the form already validates client-side, the server still validates — but don't add a redundant intermediate check.

Server Components by default. Add "use client" only when you need state, effects, or browser APIs.
Keep client components small. Prefer pushing state-free logic into Server Components.
Don't import server-only modules into client components (@/lib/db/mongodb, @matters/lib/config/env's process.env.* access).

Native <button> must set type="button" unless it genuinely submits a form — the HTML default is type="submit", which silently submits the nearest form. The shared Button components (components/ui/button.tsx, components/Button.tsx) now default to type="button"; raw <button> elements set it explicitly.
Hand-rolled modals need role="dialog" + aria-modal="true" + a label + an Escape-to-close handler. Prefer the shared Dialog primitive; if you hand-roll (to keep the ws-* theme), mirror the snippet-generator import modal.
Icon-only controls need an aria-label.

Every workspace UI surface resolves through @matters/theme — ws-* and shadcn semantic tokens, never hardcoded hex / zinc-* / rounded-* / shadow-* / backdrop-blur. Shared primitives (DarkInput/DarkTextArea/DarkSelect, GlassCard, SmartInput) are tokenized — keep them that way so all 12 theme variants + light/dark re-skin for free. Full rules: apps/workspace/CLAUDE.md and packages/theme/README.md.

Tailwind utility classes. No CSS modules, no styled-components.
Use cn(...) from @matters/lib/utils/cn (re-exported as @/lib/utils) to compose conditional classes.
Brand colors live in tailwind.config.ts theme.extend.colors.brand. Use the tokens, not raw hex.

Write comments when "why" isn't obvious. Don't write comments for "what" — the code already says what.
Update or delete stale comments in the same PR as the change. Lying comments are worse than no comments.
TODO comments need an owner + a date: // TODO(eshank, 2026-05-30): wire to feature flag service.

Unit tests via Jest (*.test.ts). Integration tests in tests/integration/.
Test the contract, not the implementation: assert what the function returns / what side effects it produces, not how it gets there.
Mock at the boundary (Clerk, Mongo, AWS SDK) — not internal modules.

Avoid await in tight loops over arrays — batch with Promise.all or runWithConcurrency (see sync-salesforce/route.ts for the pattern).
Prefer streaming for large responses (CSV exports).
Don't allocate large objects in render bodies — useMemo / outside the component.
Lazy-load heavy client libraries (Tiptap, recharts, three.js) with next/dynamic (ssr:false) so they only ship to the routes/interactions that use them — e.g. the observability panels and the snippet generator's WYSIWYG. Register big barrel packages in next.config.ts → experimental.optimizePackageImports (today: ["sharp", "framer-motion"]).
Debounce expensive derived work on hot input paths (the snippet generator regenerates + serializes on a ~150 ms debounce, not on every keystroke).

Loading…