favorite-stack

Favorite Stack

This skill captures the conventions and non-obvious rules for the favorite-stack. Most mistakes happen around the TypeScript toolchain, ESM imports, and SQL safety — focus there first.

Stack at a Glance

Category	Tool
Runtime	Node.js 24 (ESM, using keyword)
Language	TypeScript — type-check with tsgo, not tsc
Pkg mgr	pnpm (never npm/yarn)
Bundler	Vite — target es2024
Testing	Vitest — co-locate *.test.ts
Database	SQLite via better-sqlite3
Frontend	Alpine.js v3 + Pico.css v2
Logging	Pino (never console.log)
Lint/Fmt	oxlint + oxfmt

Commands

pnpm dev              # Vite dev server
pnpm build            # Production build
pnpm test             # Vitest single run
pnpm test:watch       # Vitest watch
pnpm lint             # oxlint src/
pnpm fmt              # oxfmt src/
pnpm typecheck        # tsgo --noEmit
pnpm check            # lint + fmt + typecheck (run before committing)

Critical Rules (Common Mistakes)

These are the rules most likely to be violated — check these first in any code review.

1. Use tsgo, never tsc

tsgo --noEmit   # ✅
tsc --noEmit    # ❌ — wrong compiler

2. Always use .js extensions in imports

ESM requires explicit extensions at runtime. Bundler resolution doesn't save you in all contexts.

import { logger } from './lib/logger.js';   // ✅
import { logger } from './lib/logger';      // ❌ breaks at runtime

3. import type for type-only imports

verbatimModuleSyntax: true is enabled — the compiler will error otherwise.

import type { User } from './types.js';  // ✅
import { User } from './types.js';       // ❌ type-only import must use `import type`

4. Never console.log — use Pino

oxlint enforces no-console. Use the logger singleton instead.

import { logger } from './lib/logger.js';
logger.info({ userId }, 'User created');   // ✅
console.log('User created');               // ❌ lint error

5. Never string-interpolate SQL

SQL injection risk and no type safety. Always use prepared statements.

// ✅
const getUser = db.prepare<[number], User>('SELECT * FROM users WHERE id = ?');
const user = getUser.get(userId);

// ❌
db.prepare(`SELECT * FROM users WHERE id = ${userId}`).get();

6. Use pnpm, never npm or yarn

pnpm add <pkg>      # ✅
npm install <pkg>   # ❌

Project Structure

src/
├── main.ts              # Entry point
├── app.ts               # App setup / route mounting
├── db/
│   ├── index.ts         # DB connection — WAL mode, FK ON
│   └── migrations/      # 001_init.sql, 002_add_users.sql, …
├── routes/              # One file per resource
├── middleware/
└── lib/
    ├── logger.ts        # Pino singleton
    └── errors.ts        # AppError / NotFoundError / ValidationError

Useful Patterns (Quick Reference)

For full examples, read the relevant reference file.

TypeScript — references/typescript.md

• satisfies operator, unknown narrowing, using for resources

SQLite — references/sqlite.md

• DB setup, prepared statements, transactions, migrations

Frontend — references/frontend.md

• Alpine.js state/components, Pico.css semantic HTML, card/form patterns

Logging & Errors — references/logging-errors.md

• Pino setup, child loggers, typed error classes