Eamon Hyland’s Preferences

Core Conventions

Server environment configuration

• Server configuration should be loaded from environment variables and validated with zod
• Default values should be set for dev environment
• Test defaults can be set in the test runner (e.g. bun test or vitest setup script)

Configuration should be defined in src/config.ts or src/server/config.ts (for fullstack apps)

// src/config.ts
import { z } from "zod";

const configSchema = z.object({
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  DATABASE_URL: z.string().default("sqlite.db"),
});

const parsed = configSchema.safeParse(process.env);

if (!parsed.success) {
  console.error("❌ Invalid environment variables:", parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const config = parsed.data

// src/config.ts
import { z } from "zod";

const configSchema = z.object({
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  DATABASE_URL: z.string().default("sqlite.db"),
});

const parsed = configSchema.safeParse(process.env);

if (!parsed.success) {
  console.error("❌ Invalid environment variables:", parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const config = parsed.data

// src/test/setup.ts
process.env.DATABASE_URL = ":memory:";

client -> server communication

• Prefer trpc with react query for fullstack projects (when the server and client are in the same package)
• Otherwise prefer graphql

TypeScript

• Never use @ts-ignore
• Never use as any casting or as unknown as <some-other-type>

Preferred tsconfig.json config

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

Package.json scripts

The following are my preferred set of package.json scripts. Not all scripts are relevant to all projects e.g. library packages will not have db scripts

{
  "scripts": {
    "dev": "bun run --watch src/index.ts",
    
    "db:generate": "drizzle-kit generate",
    "db:studio": "drizzle-kit studio",
    
    "typecheck": "tsc --noEmit",
    
    "format": "oxfmt src",
    "format:check": "oxfmt src --check",

    "lint": "oxlint --type-aware",
    "lint:fix": "oxlint --type-aware --fix --fix-suggestions --fix-dangerously",

    "fix": "bun format && bun lint:fix",

    "check": "concurrently 'bun:format' 'bun:lint:fix' 'bun:typecheck' 'bun:test' 'bun:test:e2e'",
    
    "test": "bun test",
    "test:e2e": "playwright test"
  }
}

Linting Setup

Use Oxlint and Oxfmt from OXC

// .oxlintrc.json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}

// .oxfmtrc.json
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "trailingComma": "all",
  "printWidth": 80,
  "ignorePatterns": []
}

Fix linting errors & formatting errors with fix script, e.g. bun run fix or pnpm run fix.

Git Hooks

Use npm dependencies simple-git-hooks & lint-staged

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && pnpm lint-staged"
  },
  "lint-staged": { "*": "pnpm fix" },
  "scripts": { "prepare": "pnpm simple-git-hooks" }
}

Test Conventions

• Test files: foo.ts → foo.test.ts (same directory)
• Use describe/it API (not test)

References