Code Standards

Coding conventions and PR process for Refresh App Web.

TypeScript Standards

Strict Mode

{
	"compilerOptions": {
		"strict": true,
		"noUnusedLocals": true,
		"noUnusedParameters": true,
		"noImplicitReturns": true
	}
}

Type Annotations

// ✅ Good - explicit types
function calculateTotal(items: Item[]): number {
	return items.reduce((sum, item) => sum + item.price, 0);
}

// ❌ Avoid - implicit any
function process(data) {
	return data.map((item) => item.value);
}

Interfaces vs Types

Use interfaces for object shapes:

interface User {
	id: string;
	name: string;
	email: string;
}

Use types for unions/intersections:

type Status = 'pending' | 'active' | 'archived';
type UserWithStatus = User & { status: Status };

Svelte 5 Standards

Use Runes

// ✅ Good - runes
let count = $state(0);
let doubled = $derived(count * 2);

$effect(() => {
	console.log('Count changed:', count);
});

// ❌ Avoid - old reactivity
let count = 0;
$: doubled = count * 2;

Props

// ✅ Good - destructured props
let { user, tenants = [] }: { user: User; tenants?: Tenant[] } = $props();

// ❌ Avoid - $$props

Event Handlers

<!-- ✅ Good - inline arrow function -->
<button onclick={() => handleClick(id)}>Click</button>

<!-- ❌ Avoid - string event handlers -->
<button on:click={() => handleClick(id)}>Click</button>

File Organization

src/routes/(authenticated)/app/feature/
├── +page.svelte          # Page component
├── +page.server.ts       # Server load function
├── +layout.svelte        # Layout (if needed)
├── components/           # Feature-specific components
│   ├── FeatureList.svelte
│   └── FeatureForm.svelte
└── utils.ts              # Feature utilities

Naming Conventions

• Components: PascalCase (Button.svelte, UserCard.svelte)

• Files: kebab-case (user-utils.ts, auth-helpers.ts)

• Functions: camelCase (getUserById, calculateTotal)

• Constants/Enums: UPPER_SNAKE_CASE (MAX_ITEMS, API_ENDPOINT)

• Types/Interfaces: PascalCase (User, ApiResponse)

Formatting

# Auto-format all files
pnpm format

# Check formatting
pnpm format --check

Configuration: .prettierrc

{
	"useTabs": true,
	"singleQuote": true,
	"trailingComma": "none",
	"printWidth": 100,
	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"]
}

Linting

pnpm lint

Configuration: eslint.config.js

Git Workflow

Branch Naming

• feature/description - New features

• fix/description - Bug fixes

• refactor/description - Code refactoring

• docs/description - Documentation

• test/description - Tests

Commit Messages

Follow Conventional Commits:

feat: add tenant switching UI
fix: resolve RLS policy issue
docs: update authentication guide
refactor: simplify session caching
test: add component tests for Button
chore: update dependencies

PR Process

1. Create branch from main

2. Make changes

3. Run tests: pnpm test && pnpm check

4. Format code: pnpm format

5. Commit with conventional message

6. Push to GitHub

7. Create PR with description

8. Wait for CI/CD checks

9. Request review

10. Address feedback

11. Squash and merge

PR Template

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Tested in browser

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings

Code Review Guidelines

As Author:

• Keep PRs small (<500 lines)

• Write descriptive PR description

• Add screenshots for UI changes

• Respond to feedback promptly

As Reviewer:

• Be constructive and kind

• Test the changes locally

• Check for edge cases

• Approve when ready

Related Documentation

• Getting Started

• Testing Guide

---

Last updated: October 2025