coding-styleguide-js-ts

JavaScript & TypeScript

• Use TypeScript. If .js files are requested, use JSDoc type annotations
• Prefer functional over imperative
• Prefer immutability
• Priority rule (MUST): order every file by importance. Start with the primary logic and keep less important helpers/details at the end. Do not put small helpers, secondary types, or uninteresting constants above the main export just to satisfy "define before call".

Formatting

• Use the repository's formatter (Prettier or Oxfmt) and its config; do not hand-format code the formatter would rewrite

Imports & exports

• Use ESM unless you're editing a CommonJS file
• Follow the consuming repository's established import-specifier convention (extensions vs extensionless; .js vs .ts in TypeScript source files)
• Determine convention from nearby files and configuration before introducing new imports
• Keep import style consistent within a module/package; avoid mixed styles unless already established
• If conventions are unclear or conflicting, ask the user before changing or introducing import-specifier style
• Avoid default imports and default exports
• Avoid barrel files (index files that only re-export) unless its a package entry file

File structure

• Do not add a file header comment by default
• For complex or high-impact files only, add a short context comment near the top (3-6 lines) that explains purpose, where to start reading, and non-obvious caveats
• Then imports
• Then the file's primary export(s) / main classes and functions (order by importance relative to the file purpose)
• Then supporting types, less important constants/variables, and private helpers at the bottom
• Calling a helper from a function body does not require the helper to appear above that function; only load-time / TDZ constraints do
• Exception: when module execution requires a binding to be initialized before it is used at load time, define it earlier

Naming Conventions

• camelCase for variables, functions, methods
• PascalCase for classes, enums and React components
• SCREAMING_SNAKE_CASE for build-time constants
• kebab-case for file names, CSS classes and DOM ids
• Stick to existing naming conventions if present (e.g. camelCase and PascalCase for file names)
• Use specific names instead of unspecific abbreviations like obj, arr and err
• Only use abbreviations when they are widely used like Api
• Abbreviations should be treated as separate words (e.g. Api instead of API)
• Use short names when the variable or function is private and only accessible in the current file
• Use longer and more specific names when the variable or function is exported and visible across the whole project
• Use auxiliary verbs (e.g., isLoading, hasError) for boolean variables and type guards
• Name variables and parameters after their type, unless there is a good reason not to (e.g. multiple instances of the same type in scope, or a more meaningful domain name)