coding-style

Coding style:

• Favor async run() { over run = async () => { inside ES6 classes
• Favor if (!(err instanceof Error)) { throw new Error(Was thrown a non-error: ${err}) } inside catch blocks to ensure the error is always an instance of Error
• Favor using real paths (../lib/schemas.ts) over aliases (@/app/lib/schemas).
• Favor for (const comment of comments) { over comments.forEach((comment) => {
• Favor named exports over default exports, with the exception of Next.js pages
• Avoid namespace * imports unless the API is intentionally consumed as a namespace. Prefer named imports so usage is explicit and bundlers can optimize.
• Avoid broad file-level lint suppressions. Prefer the narrowest scoped suppression on the exact line, with a reason when the exception is not obvious.
• Preserve existing dependency import paths and module-system interop unless the change is required and explained. Do not rewrite package imports to node_modules/..., switch ESM/CJS shapes, or add duplicate export styles just to satisfy local tooling.
• Do not wrap each function body and function call in try/catch blocks. It pollutes the code. Assume we will always have an e.g. main().catch((err) => { console.error(err); process.exit(1) }) to catch us. I repeat: Avoid over-use of try-catch such as try { // foo } catch (err) { console.error('error while foo'); throw err }, assume we catch errors on a higher level and do not need the extra explananation.
• If you must use try/catch, for simple cases, favor alphalib/tryCatch.ts (const [err, data] = await tryCatch(promise)) over let data; try { data = await promise } catch (err) { }
• Before creating new files and new code, see if we can leverage existing work, maybe slighty adapt that without breaking BC, to keep things DRY.
• Favor early exits, so quickly continue, return false (or throw if needed), over nesting everything in positive conditions, creating christmas trees.
• Use Prettier with 100 char line width, single quotes for JS/TS, semi: false
• Use descriptive names: PascalCase for components/types, camelCase for variables/methods/schemas
• Alphabetize imports, group by source type (built-in/external/internal)
• Preserve existing sorted lists and config ordering unless intentionally changing the order.
• Write code in English: identifiers, file names, comments, log and error messages, and operator-facing CLI output. Text written for a specific audience, such as customer messages, templates and translated UI copy, stays in that audience's language. Existing non-English code needs no rename for its own sake, but new code and comments are English, and code is translated before it moves into shared code such as alphalib.
• Favor US English over UK English, so summarizeError over summarise Error
• Favor .replaceAll('a', 'b) over .replace(/a/g, 'b') or .replace(new RegExp('a', 'g'), 'b') when the only need for regeses was replacing all strings. That's usually both easier to read and more performant.
• Use typographic characters: ellipsis (…) instead of ..., curly quotes (' ") instead of straight quotes in user-facing text
• Generated text files should end with a trailing newline. Do not trim serializer output when the serializer intentionally emits POSIX-style text.
• Comments should explain why code exists or why an exception is needed, not narrate what the next line already says.
• Use JSDoc block comments for exported constants, functions, classes, and types when documenting their purpose or contract. Use regular line comments for local quirks, reasoning, or exceptions.
• Do not put TODOs, internal implementation notes, or future-work placeholders in user-facing text or schema descriptions. Put those in code comments, issues, or docs for maintainers instead.
• Put API keys and secrets in .env files, not hardcoded in components
• Do not return raw errors, stack traces, third-party responses, payment objects, database errors, or credential data to clients. Show sanitized user-facing messages and log only redacted diagnostic details server-side.
• When wrapping or rethrowing an error, preserve the original value with new Error(message, { cause: error }) when possible instead of stringifying it away.
• Remove temporary debug logging/instrumentation before merge. Keep new logs only when they are intentional, useful in production, and do not expose sensitive data.
• Check for existing hooks before creating new ones (e.g., useUppy() for Uppy functionality)