admin/changemaker.lite

Fork 0

bunker-admin 7895ce683e Tonne of debugging - getting ready for the production builds

2026-02-16 10:44:18 -07:00

18 KiB

Raw Blame History

Code Style Guide

Coding standards and style conventions for Changemaker Lite V2.

Overview

Consistent code style improves:

Readability: Easier to understand code
Maintainability: Easier to modify code
Collaboration: Reduces merge conflicts
Quality: Catches common errors

This guide covers TypeScript, ESLint, Prettier, and naming conventions.

Tools

TypeScript

Version: 5.x Config: tsconfig.json (api/ and admin/)

Strict Mode: Enabled

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

ESLint

Version: 8.x Config: .eslintrc.js (api/ and admin/)

Plugins:

@typescript-eslint/eslint-plugin
eslint-plugin-react (admin only)
eslint-plugin-react-hooks (admin only)

Prettier

Version: 3.x Config: .prettierrc

Format on save: Enabled (VSCode)

TypeScript Configuration

API tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Admin tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "types": ["vite/client"]
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

ESLint Rules

API .eslintrc.js

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: 'module',
    project: './tsconfig.json'
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking'
  ],
  plugins: ['@typescript-eslint'],
  root: true,
  env: {
    node: true,
    es2022: true
  },
  rules: {
    // TypeScript
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/explicit-function-return-type': 'off',
    '@typescript-eslint/explicit-module-boundary-types': 'off',
    '@typescript-eslint/no-unused-vars': [
      'error',
      { argsIgnorePattern: '^_' }
    ],
    '@typescript-eslint/no-floating-promises': 'error',
    '@typescript-eslint/await-thenable': 'error',

    // General
    'no-console': ['warn', { allow: ['warn', 'error'] }],
    'no-debugger': 'error',
    'prefer-const': 'error',
    'no-var': 'error',
    'eqeqeq': ['error', 'always'],
    'curly': ['error', 'all']
  }
};

Admin .eslintrc.js

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
    ecmaFeatures: {
      jsx: true
    },
    project: './tsconfig.json'
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:@typescript-eslint/recommended'
  ],
  plugins: ['react', 'react-hooks', '@typescript-eslint'],
  root: true,
  env: {
    browser: true,
    es2020: true
  },
  settings: {
    react: {
      version: 'detect'
    }
  },
  rules: {
    // React
    'react/react-in-jsx-scope': 'off', // React 17+
    'react/prop-types': 'off', // Use TypeScript
    'react-hooks/rules-of-hooks': 'error',
    'react-hooks/exhaustive-deps': 'warn',

    // TypeScript
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/explicit-function-return-type': 'off',
    '@typescript-eslint/no-unused-vars': [
      'error',
      { argsIgnorePattern: '^_' }
    ],

    // General
    'no-console': ['warn', { allow: ['warn', 'error'] }],
    'no-debugger': 'error',
    'prefer-const': 'error',
    'no-var': 'error',
    'eqeqeq': ['error', 'always']
  }
};

Key Rules Explained

@typescript-eslint/no-explicit-any - Prevents any type

// ❌ Bad
function foo(data: any) {}

// ✅ Good
function foo(data: User) {}
function foo(data: unknown) {} // Use unknown instead

@typescript-eslint/no-unused-vars - Prevents unused variables

// ❌ Bad
const foo = 1; // Never used

// ✅ Good
const _foo = 1; // Prefix with _ to ignore

@typescript-eslint/no-floating-promises - Requires await/catch

// ❌ Bad
asyncFunction(); // Promise not handled

// ✅ Good
await asyncFunction();
asyncFunction().catch(console.error);
void asyncFunction(); // Explicitly ignore

react-hooks/exhaustive-deps - Validates useEffect dependencies

// ❌ Bad
useEffect(() => {
  fetchUser(userId);
}, []); // Missing userId dependency

// ✅ Good
useEffect(() => {
  fetchUser(userId);
}, [userId]);

Prettier Configuration

.prettierrc

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "useTabs": false,
  "trailingComma": "es5",
  "printWidth": 100,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

.prettierignore

node_modules
dist
build
coverage
.vite
.cache
*.min.js
*.min.css
package-lock.json

Format Commands

# Format all files
npm run format

# Check formatting (CI)
npm run format:check

# Format specific file
npx prettier --write src/modules/auth/auth.service.ts

Naming Conventions

Files and Directories

Files: kebab-case

auth.service.ts
user.controller.ts
campaign.routes.ts
locations-page.tsx

Components: PascalCase

UserCard.tsx
LoginForm.tsx
MapView.tsx

Test files: Match source file with .test or .spec

auth.service.test.ts
UserCard.test.tsx

Directories: kebab-case

src/modules/auth/
src/components/map/
src/pages/public/

Variables and Functions

Variables: camelCase

const userName = 'John';
const isActive = true;
const totalCount = 100;

Constants: UPPER_SNAKE_CASE

const API_URL = 'http://localhost:4000';
const MAX_RETRIES = 3;
const DEFAULT_PAGE_SIZE = 50;

Functions: camelCase

function getUserById(id: number) {}
async function fetchCampaigns() {}
const handleClick = () => {};

Private methods: Prefix with underscore (optional)

class UserService {
  async getUser(id: number) {}

  private async _hashPassword(password: string) {}
}

Types and Interfaces

Types/Interfaces: PascalCase

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

type UserRole = 'USER' | 'ADMIN';

interface CreateUserInput {
  email: string;
  password: string;
}

Enums: PascalCase, members UPPER_SNAKE_CASE

enum UserRole {
  USER = 'USER',
  ADMIN = 'ADMIN',
  SUPER_ADMIN = 'SUPER_ADMIN'
}

React Components

Components: PascalCase

export function UserCard({ user }: { user: User }) {
  return <div>{user.name}</div>;
}

Props interfaces: ComponentNameProps

interface UserCardProps {
  user: User;
  onEdit?: (user: User) => void;
}

export function UserCard({ user, onEdit }: UserCardProps) {
  return <div>{user.name}</div>;
}

Event handlers: handle[Event] or on[Event]

function UserForm() {
  const handleSubmit = () => {};
  const onEmailChange = (email: string) => {};

  return <form onSubmit={handleSubmit}>...</form>;
}

Database Models

Prisma models: PascalCase (singular)

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
}

model Campaign {
  id    Int    @id @default(autoincrement())
  title String
}

Table names: snake_case (plural)

model User {
  @@map("users")
}

model Campaign {
  @@map("campaigns")
}

Fields: camelCase in schema, snake_case in database

model User {
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
}

File Organization

Module Structure

src/modules/auth/
├── auth.service.ts        # Business logic
├── auth.routes.ts         # Express routes
├── auth.schemas.ts        # Zod validation schemas
└── auth.service.test.ts   # Tests

Import Order

External libraries
Internal modules (absolute imports)
Relative imports
Types
Styles (frontend)

// 1. External libraries
import express from 'express';
import { z } from 'zod';

// 2. Internal modules
import { authenticate } from '@/middleware/auth';
import { UserService } from '@/modules/users/user.service';

// 3. Relative imports
import { AuthService } from './auth.service';
import { loginSchema } from './auth.schemas';

// 4. Types
import type { Request, Response } from 'express';
import type { User } from '@prisma/client';

// 5. Styles (frontend only)
import './auth.css';

Export Patterns

Named exports (preferred)

// auth.service.ts
export class AuthService {
  async login() {}
}

// usage
import { AuthService } from './auth.service';

Default exports (React components)

// UserCard.tsx
export default function UserCard() {
  return <div>...</div>;
}

// usage
import UserCard from './UserCard';

Re-exports (index files)

// modules/auth/index.ts
export { AuthService } from './auth.service';
export { authRoutes } from './auth.routes';
export * from './auth.schemas';

Code Patterns

Async/Await

Always use async/await (not callbacks or .then()):

Good:

async function getUser(id: number) {
  const user = await prisma.user.findUnique({ where: { id } });
  return user;
}

Bad:

function getUser(id: number) {
  return prisma.user.findUnique({ where: { id } }).then(user => {
    return user;
  });
}

Error Handling

Use try/catch for error handling:

Good:

async function createUser(data: CreateUserInput) {
  try {
    const user = await prisma.user.create({ data });
    return user;
  } catch (error) {
    logger.error('Failed to create user', error);
    throw new Error('User creation failed');
  }
}

Bad:

async function createUser(data: CreateUserInput) {
  const user = await prisma.user.create({ data }); // Unhandled error
  return user;
}

Optional Chaining

Use optional chaining for nullable values:

Good:

const email = user?.email;
const city = user?.address?.city;

Bad:

const email = user && user.email;
const city = user && user.address && user.address.city;

Nullish Coalescing

Use ?? for default values (not ||):

Good:

const limit = query.limit ?? 50;
const name = user.name ?? 'Unknown';

Bad:

const limit = query.limit || 50; // Fails for 0
const name = user.name || 'Unknown'; // Fails for ''

Array Methods

Prefer functional array methods:

Good:

const activeUsers = users.filter(u => u.isActive);
const emails = users.map(u => u.email);
const total = amounts.reduce((sum, amt) => sum + amt, 0);

Bad:

const activeUsers = [];
for (let i = 0; i < users.length; i++) {
  if (users[i].isActive) {
    activeUsers.push(users[i]);
  }
}

Object Destructuring

Use destructuring for object properties:

Good:

const { email, name, role } = user;
const { limit = 50, page = 1 } = query;

Bad:

const email = user.email;
const name = user.name;
const role = user.role;

Template Literals

Use template literals for string interpolation:

Good:

const message = `Hello, ${user.name}!`;
const url = `/api/users/${userId}`;

Bad:

const message = 'Hello, ' + user.name + '!';
const url = '/api/users/' + userId;

Comments and Documentation

JSDoc for Functions

Document public functions with JSDoc:

/**
 * Creates a new user with the given email and password.
 *
 * @param email - User's email address
 * @param password - User's password (will be hashed)
 * @returns Created user object
 * @throws {Error} If user already exists
 */
async function createUser(email: string, password: string): Promise<User> {
  // ...
}

Inline Comments

Use inline comments for complex logic:

// Calculate pagination offset
const offset = (page - 1) * limit;

// Hash password with 10 salt rounds
const hashedPassword = await bcrypt.hash(password, 10);

// Point-in-polygon ray-casting algorithm
let inside = false;
for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
  // ... complex logic
}

Avoid Obvious Comments

Don't comment obvious code:

Good:

const isValid = email.includes('@');

Bad:

// Check if email is valid
const isValid = email.includes('@');

TODO Comments

Use TODO for future work:

// TODO: Add pagination support
async function getUsers() {
  return prisma.user.findMany();
}

// FIXME: This doesn't handle edge case when user is null
const userName = user.name;

Git Commit Messages

Conventional Commits

Use conventional commit format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation
style: Formatting
refactor: Code restructuring
test: Adding tests
chore: Maintenance

Examples:

feat(auth): add JWT refresh token rotation
fix(map): correct point-in-polygon calculation
docs(api): update authentication guide
refactor(users): extract service layer
test(campaigns): add unit tests for CRUD operations

With scope and body:

git commit -m "feat(campaigns): add email sending

Implements BullMQ queue for async email delivery.
Adds retry logic and error handling.

Closes #123"

Co-Authoring with Claude

When Claude assists with code:

git commit -m "$(cat <<'EOF'
feat(auth): add JWT refresh token rotation

Implemented atomic refresh token rotation to prevent
race conditions during concurrent refresh requests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

React Patterns

Functional Components

Always use functional components (not class components):

Good:

export function UserCard({ user }: UserCardProps) {
  return <div>{user.name}</div>;
}

Bad:

export class UserCard extends React.Component<UserCardProps> {
  render() {
    return <div>{this.props.user.name}</div>;
  }
}

Hooks

Use hooks for state and side effects:

function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    async function fetchUsers() {
      setLoading(true);
      const data = await api.get('/users');
      setUsers(data);
      setLoading(false);
    }
    fetchUsers();
  }, []);

  if (loading) return <div>Loading...</div>;

  return <div>{users.map(u => <UserCard key={u.id} user={u} />)}</div>;
}

Props Destructuring

Destructure props in function signature:

Good:

function UserCard({ user, onEdit }: UserCardProps) {
  return <div onClick={() => onEdit?.(user)}>{user.name}</div>;
}

Bad:

function UserCard(props: UserCardProps) {
  return <div onClick={() => props.onEdit?.(props.user)}>{props.user.name}</div>;
}

Key Prop

Always provide key for list items:

Good:

{users.map(user => (
  <UserCard key={user.id} user={user} />
))}

Bad:

{users.map((user, index) => (
  <UserCard key={index} user={user} />
))}

Editor Integration

VSCode Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Pre-commit Hook

Install husky for pre-commit checks:

npm install --save-dev husky lint-staged
npx husky install

package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  },
  "scripts": {
    "prepare": "husky install"
  }
}

.husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

Quick Reference

Run Linting

# Lint
npm run lint

# Auto-fix
npm run lint:fix

# Format
npm run format

# Type-check
npm run type-check

Common Fixes

# Fix all auto-fixable issues
npm run lint:fix && npm run format

# Type-check both projects
cd api && npm run type-check && cd ../admin && npm run type-check

Setup: Local Development Setup
TypeScript: TypeScript Guide
Testing: Testing Guide
Git: Git Workflow

Summary

You now know:

✅ TypeScript configuration (strict mode)
✅ ESLint rules and plugins
✅ Prettier configuration
✅ Naming conventions (files, variables, types)
✅ File organization patterns
✅ Code patterns (async/await, error handling)
✅ Comment and documentation standards
✅ Git commit message format
✅ React patterns and best practices
✅ Editor integration (VSCode, pre-commit hooks)

Quick Start:

# Auto-fix and format
npm run lint:fix && npm run format

# Check types
npm run type-check

# Pre-commit
npm run lint:fix && npm run format && npm run type-check

18 KiB Raw Blame History

Code Style Guide

Overview

Tools

TypeScript

ESLint

Prettier

TypeScript Configuration

API tsconfig.json

Admin tsconfig.json

ESLint Rules

API .eslintrc.js

Admin .eslintrc.js

Key Rules Explained

Prettier Configuration

.prettierrc

.prettierignore

Format Commands

Naming Conventions

Files and Directories

Variables and Functions

Types and Interfaces

React Components

Database Models

File Organization

Module Structure

Import Order

Export Patterns

Code Patterns

Async/Await

Error Handling

Optional Chaining

Nullish Coalescing

Array Methods

Object Destructuring

Template Literals

Comments and Documentation

JSDoc for Functions

Inline Comments

Avoid Obvious Comments

TODO Comments

Git Commit Messages

Conventional Commits

Co-Authoring with Claude

React Patterns

Functional Components

Hooks

Props Destructuring

Key Prop

Editor Integration

VSCode Settings

Pre-commit Hook

Quick Reference

Run Linting

Common Fixes

Related Documentation

Summary

18 KiB

Raw Blame History