loco-admin-web/specs/CODING_CONVENTION.md

Coding Conventions

Stack

• Language: TypeScript (strict mode)
• Framework: SvelteKit 5 (Runes mode)
• Package Manager: npm
• Styling: Tailwind CSS v4
• Testing: Vitest (unit/component), Playwright (e2e)
• Linting: ESLint + Prettier

Formatting

• Tabs for indentation, single quotes, trailing commas, semicolons
• Print width: 100 characters
• Import order: node built-ins → third-party → $app/* → $lib/* → relative
• Always use absolute imports — prefer $lib/... and $app/... over relative paths. The only allowed relative imports are SvelteKit auto-generated route types (./$types), which cannot be referenced absolutely
• Always run Prettier and ESLint (npm run format && npx eslint --fix) before finalizing any code change — never hand-format

Svelte

• Always use Svelte 5 Runes ($state, $derived, $effect) — no legacy Options API
• Store reactive state in *.svelte.ts files under src/lib/stores/
• Run svelte-autofixer (via MCP) on all new Svelte code before finalizing
• Components should be exported through index.ts under $lib/components/{ComponentName}

TypeScript

• No any — use unknown and narrow explicitly
• Prefer type over interface for data shapes; use interface for extension points
• Co-locate types with the module that owns them
• Prefer arrow functions over function declarations when assigning to a variable — function declarations are fine for class methods; use arrows everywhere else:

  // ✗ function expression as variable
  const handler = function (x: number) {
  	return x * 2;
  };

  // ✓ arrow function
  const handler = (x: number) => x * 2;

  // ✗ top-level named function (not a variable)
  function helper(x: number) {
  	return x * 2;
  }

  // ✓ class method (not a variable)
  class Foo {
  	bar() {
  		return 1;
  	}
  }

• Exports go at the bottom of the file — never use inline export on a declaration. Collect all public symbols in a single export / export type statement at the end:

  // ✗ inline export
  export type Foo = { ... };
  export const bar = () => { ... }

  // ✓ bottom export
  type Foo = { ... };
  const bar = () => { ... }

  export type { Foo };
  export { bar };