Coding Standards

This skill should be used when the user asks about "coding standards", "code style", "how should I write this", "is this correct style", "what's the convention for", "interface vs type", "should I use React.FC", "how do we handle errors", "tryCatch pattern", "db query style", "arrow functions", "named vs default export", "how to structure this file", "barrel files", "institutionId", "multi-tenant", "page-content pattern", "naming conventions", "SCREAMING_SNAKE_CASE", "reviewing a PR", "page width", "content width", "PageLayout", "does this pass code review", or wants to know whether code follows Sylla's Next.js 16 repository standards.

sylla-bv c22cdd3 2 files · 37.4 KB Updated Sep 17, 2026

Install

Press C to copy

$ npx skillmds@latest add sylla-bv/coding-standards

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/sylla-bv/coding-standards.svg)](https://skillmd.com/skills/sylla-bv/coding-standards)

Trust & safety

Audits pending

Not yet audited · commit c22cdd3

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Coding Standards

Sylla-specific standards for the Next.js 16 App Router codebase. All rules are settled and enforced in code review. Full rationale and code examples for every rule are in references/standards.md.

How to Apply This Skill

For quick lookups (rule name, convention, where a file belongs), use the Quick Reference tables below.
For rationale, code examples, or edge cases, consult references/standards.md.
When reviewing code, run through the Code Smell Checklist at the bottom of this file.

All work must satisfy readability, KISS, DRY, YAGNI, and security — specifically: no as any, mandatory institutionId scoping on every DB query, and Server Components by default.

Quick Reference

TypeScript

Rule	Standard
Object shapes, props, data models	`interface`
Unions, intersections, mapped types	`type`
`React.FC<T>`	Banned — type props with `interface` directly
Named type for trivial one-off shape	Banned — use an inline type annotation instead
Return types on exported functions	Required
Return types on internal helpers	Inferred
Intentional absence (DB returns)	`null`
Optional params	`undefined` (use `?`)
Null guards	Optional chaining + nullish coalescing

Functions & Components

Rule	Standard
Function syntax	Arrow functions always
`function` keyword	Banned — except Next.js file-convention `export default function`
Single-component file	`export default`
Multi-export file	Named exports
Props type name	`interface ComponentNameProps`
Short props list (<4)	Destructure in signature
Long props list (4+)	Named `props` param, destructure in body
Default values	In destructure signature, not body

Error Handling

Rule	Standard
Exported functions that can fail	Wrap entire body in `tryCatch`, return `Result<T>`
`throw` from exported functions	Banned
Consuming `Result<T>`	Check `result.data` branch before use
Calling server actions from client	No `try/catch` needed — server action is wrapped in `tryCatch`; handle `Result<T>` branches
React-query mutations	Handle errors via `onError` callback, not `try/catch` in `mutationFn`

Database

Rule	Standard
Query syntax	Prefer `db.query.*` (relational API); use `db.select()` for inner joins / aggregations
Raw SQL	Banned (except custom migrations)
Multiple raw Drizzle queries	`db.batch()` — single round-trip
Independent async function calls	`Promise.all` — not `db.batch()`
`institutionId` on user/institution queries	Required unless `isSuperAdmin` confirms admin

Caching

Rule	Standard
Caching directive	`'use cache'` at top of function body (NOT `unstable_cache`)
Cache tags	`cacheTag(CACHE_TAGS.X, ...)` — always use `CACHE_TAGS` constant, never hardcode strings
Cache lifetime	`cacheLife('profile')` — use named profiles from `next.config.mjs`, never hardcode durations
Invalidation in Server Actions	`updateTag(tag)` — instant UI refresh
Invalidation in Route Handlers/jobs	`revalidateTag(tag, 'max')` — `'max'` expiry required
`unstable_cache`	Banned — fully migrated

File & Naming

Thing	Convention
Files & folders	kebab-case
Variables	camelCase
Functions	camelCase, verb-first
Components	PascalCase
Interfaces & types	PascalCase
Hooks	`use` prefix
Boolean vars	`is`, `has`, `can` prefix
Constants (all scopes)	`SCREAMING_SNAKE_CASE`
Barrel `index.ts`	Avoid — direct imports via alias

Where Things Live

What	Where
Reusable DB query	`src/db/queries/[domain].ts`
Route-specific server action	`src/app/.../[route]/_actions.ts`
Reusable server action (non-DB)	`src/actions/[feature].ts`
React component	`src/components/[domain]/`
Custom hook	`src/hooks/use-[name].ts`
Shared constants	`src/lib/constants.ts`
Shared utility functions	`src/lib/utils/[domain].ts`
Shared importable types (plain TS)	`src/lib/types/[domain].ts`
Database-inferred types	`src/db/types.ts`
Zod schemas (validation)	`src/schemas/[domain].ts`
Component-specific types	`src/components/[domain]/types.ts`
Ambient global declarations	`/types/[name].d.ts` — never import directly

React & Next.js

Rule	Standard
Async	`async/await` always
Parallel non-DB fetches	`Promise.all`
Parallel DB fetches	`db.batch()`
Conditionals	Early returns over nested ternaries
State that depends on previous	Functional updater `setX(prev => ...)`
`page-content.tsx`	Use when page is client-driven but needs a one-time server data load
Routes with top-level `await`	Must have sibling `loading.tsx`
Page content width	Set via `PageLayout` `contentWidth` prop (`'narrow'` \| `'wide'` \| `'default'`) — avoid ad-hoc `mx-auto max-w-*` on page roots

Code Smell Checklist

Before opening a PR, check:

Function >~40 lines — split it
3 levels of nesting — use early returns
Magic number/string — extract to SCREAMING_SNAKE_CASE constant
as any — find the correct type
type for a named object shape — change to interface
Named interface/type for a trivial shape used in one place — inline it
React.FC<T> — remove it
function keyword (non–file-convention) — convert to arrow
Named export on single-component file — convert to default export
Promise.all for DB queries — replace with db.batch()
throw inside exported function — wrap in tryCatch
Missing institutionId in DB query (and no isSuperAdmin check) — multi-tenant violation
middleware.ts — must be proxy.ts
Wrapper function that only calls through — delete it
Barrel index.ts without justification — remove, use direct imports
interface/type exported from a 'use server' file — move to src/lib/types/[domain].ts (types) or src/schemas/[domain].ts (Zod schemas)
Sequential for loop over independent async calls — replace with Promise.all
unstable_cache usage — replace with 'use cache' directive
Hardcoded cache tag string — use CACHE_TAGS constant from src/lib/constants.ts
updateTag called from Route Handler — will silently fail; use revalidateTag(tag, 'max') instead
revalidateTag called from Server Action without 'max' — use updateTag for instant refresh
Cached function returning error fallback data — caches the error state; throw instead so cache is skipped
Function appears computationally heavy or performs slow I/O (large DB queries, external API calls, expensive transforms) — ask if it should be wrapped with 'use cache'

---name: coding-standardsdescription: This skill should be used when the user asks about "coding standards", "code style", "how should I write this", "is this correct style", "what's the convention for", "interface vs type", "should I use React.FC", "how do we handle errors", "tryCatch pattern", "db query style", "arrow functions", "named vs default export", "how to structure this file", "barrel files", "institutionId", "multi-tenant", "page-content pattern", "naming conventions", "SCREAMING_SNAKE_CASE", "reviewing a PR", "page width", "content width", "PageLayout", "does this pass code review", or wants to know whether code follows Sylla's Next.js 16 repository standards.---# Coding StandardsSylla-specific standards for the Next.js 16 App Router codebase. All rules are settled and enforced in code review. Full rationale and code examples for every rule are in **`references/standards.md`**.## How to Apply This Skill- For quick lookups (rule name, convention, where a file belongs), use the Quick Reference tables below.- For rationale, code examples, or edge cases, consult `references/standards.md`.- When reviewing code, run through the Code Smell Checklist at the bottom of this file.---All work must satisfy readability, KISS, DRY, YAGNI, and security — specifically: no `as any`, mandatory `institutionId` scoping on every DB query, and Server Components by default.---## Quick Reference### TypeScript| Rule | Standard ||------|----------|| Object shapes, props, data models | `interface` || Unions, intersections, mapped types | `type` || `React.FC<T>` | Banned — type props with `interface` directly || Named type for trivial one-off shape | Banned — use an inline type annotation instead || Return types on exported functions | Required || Return types on internal helpers | Inferred || Intentional absence (DB returns) | `null` || Optional params | `undefined` (use `?`) || Null guards | Optional chaining + nullish coalescing |### Functions & Components| Rule | Standard ||------|----------|| Function syntax | Arrow functions always || `function` keyword | Banned — except Next.js file-convention `export default function` || Single-component file | `export default` || Multi-export file | Named exports || Props type name | `interface ComponentNameProps` || Short props list (<4) | Destructure in signature || Long props list (4+) | Named `props` param, destructure in body || Default values | In destructure signature, not body |### Error Handling| Rule | Standard ||------|----------|| Exported functions that can fail | Wrap entire body in `tryCatch`, return `Result<T>` || `throw` from exported functions | Banned || Consuming `Result<T>` | Check `result.data` branch before use || Calling server actions from client | No `try/catch` needed — server action is wrapped in `tryCatch`; handle `Result<T>` branches || React-query mutations | Handle errors via `onError` callback, not `try/catch` in `mutationFn` |### Database| Rule | Standard ||------|----------|| Query syntax | Prefer `db.query.*` (relational API); use `db.select()` for inner joins / aggregations || Raw SQL | Banned (except custom migrations) || Multiple raw Drizzle queries | `db.batch()` — single round-trip || Independent async function calls | `Promise.all` — not `db.batch()` || `institutionId` on user/institution queries | Required unless `isSuperAdmin` confirms admin |### Caching| Rule | Standard ||------|----------|| Caching directive | `'use cache'` at top of function body (NOT `unstable_cache`) || Cache tags | `cacheTag(CACHE_TAGS.X, ...)` — always use `CACHE_TAGS` constant, never hardcode strings || Cache lifetime | `cacheLife('profile')` — use named profiles from `next.config.mjs`, never hardcode durations || Invalidation in Server Actions | `updateTag(tag)` — instant UI refresh || Invalidation in Route Handlers/jobs | `revalidateTag(tag, 'max')` — `'max'` expiry required || `unstable_cache` | Banned — fully migrated |### File & Naming| Thing | Convention ||-------|-----------|| Files & folders | kebab-case || Variables | camelCase || Functions | camelCase, verb-first || Components | PascalCase || Interfaces & types | PascalCase || Hooks | `use` prefix || Boolean vars | `is`, `has`, `can` prefix || Constants (all scopes) | `SCREAMING_SNAKE_CASE` || Barrel `index.ts` | Avoid — direct imports via alias |### Where Things Live| What | Where ||------|-------|| Reusable DB query | `src/db/queries/[domain].ts` || Route-specific server action | `src/app/.../[route]/_actions.ts` || Reusable server action (non-DB) | `src/actions/[feature].ts` || React component | `src/components/[domain]/` || Custom hook | `src/hooks/use-[name].ts` || Shared constants | `src/lib/constants.ts` || Shared utility functions | `src/lib/utils/[domain].ts` || Shared importable types (plain TS) | `src/lib/types/[domain].ts` || Database-inferred types | `src/db/types.ts` || Zod schemas (validation) | `src/schemas/[domain].ts` || Component-specific types | `src/components/[domain]/types.ts` || Ambient global declarations | `/types/[name].d.ts` — never import directly |### React & Next.js| Rule | Standard ||------|----------|| Async | `async/await` always || Parallel non-DB fetches | `Promise.all` || Parallel DB fetches | `db.batch()` || Conditionals | Early returns over nested ternaries || State that depends on previous | Functional updater `setX(prev => ...)` || `page-content.tsx` | Use when page is client-driven but needs a one-time server data load || Routes with top-level `await` | Must have sibling `loading.tsx` || Page content width | Set via `PageLayout` `contentWidth` prop (`'narrow'` \| `'wide'` \| `'default'`) — avoid ad-hoc `mx-auto max-w-*` on page roots |---## Code Smell ChecklistBefore opening a PR, check:- [ ] Function >~40 lines — split it- [ ] >3 levels of nesting — use early returns- [ ] Magic number/string — extract to `SCREAMING_SNAKE_CASE` constant- [ ] `as any` — find the correct type- [ ] `type` for a named object shape — change to `interface`- [ ] Named `interface`/`type` for a trivial shape used in one place — inline it- [ ] `React.FC<T>` — remove it- [ ] `function` keyword (non–file-convention) — convert to arrow- [ ] Named export on single-component file — convert to default export- [ ] `Promise.all` for DB queries — replace with `db.batch()`- [ ] `throw` inside exported function — wrap in `tryCatch`- [ ] Missing `institutionId` in DB query (and no `isSuperAdmin` check) — multi-tenant violation- [ ] `middleware.ts` — must be `proxy.ts`- [ ] Wrapper function that only calls through — delete it- [ ] Barrel `index.ts` without justification — remove, use direct imports- [ ] `interface`/`type` exported from a `'use server'` file — move to `src/lib/types/[domain].ts` (types) or `src/schemas/[domain].ts` (Zod schemas)- [ ] Sequential `for` loop over independent async calls — replace with `Promise.all`- [ ] `unstable_cache` usage — replace with `'use cache'` directive- [ ] Hardcoded cache tag string — use `CACHE_TAGS` constant from `src/lib/constants.ts`- [ ] `updateTag` called from Route Handler — will silently fail; use `revalidateTag(tag, 'max')` instead- [ ] `revalidateTag` called from Server Action without `'max'` — use `updateTag` for instant refresh- [ ] Cached function returning error fallback data — caches the error state; throw instead so cache is skipped- [ ] Function appears computationally heavy or performs slow I/O (large DB queries, external API calls, expensive transforms) — ask if it should be wrapped with `'use cache'`

sylla-bv/sylla-skills/tree/main/nextjs/coding-standards commit c22cdd3c21

Frequently asked questions

npx skillmds@latest add sylla-bv/coding-standards