seastem-electronjs/AGENTS.md

AGENTS.md - AI Coding Agent Guidelines

Guidelines for AI agents working in this Bun monorepo.

Project Overview

This project uses Bun exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with bun — use bun install for dependencies and bun run <script> for scripts. Always prefer bun run <script> over bun <script> to avoid conflicts with Bun built-in subcommands (e.g. bun build invokes Bun's bundler, NOT your package.json script). Never use npm, npx, or node.

• Monorepo: Bun workspaces + Turborepo orchestration
• Runtime: Bun (see mise.toml for version) — NOT Node.js
• Package Manager: Bun — NOT npm / yarn / pnpm
• Apps:
  • apps/server - TanStack Start fullstack web app (see apps/server/AGENTS.md)
  • apps/desktop - Electron desktop shell, sidecar server pattern (see apps/desktop/AGENTS.md)
• Packages: packages/tsconfig (shared TS configs)

Build / Lint / Test Commands

Root Commands (via Turbo)

bun run dev              # Start all apps in dev mode
bun run build            # Build all apps
bun run compile          # Compile server to standalone binary (current platform)
bun run compile:darwin   # Compile server for macOS (arm64 + x64)
bun run compile:linux    # Compile server for Linux (x64 + arm64)
bun run compile:windows  # Compile server for Windows x64
bun run dist             # Package desktop distributable (current platform)
bun run dist:linux       # Package desktop for Linux (x64 + arm64)
bun run dist:mac         # Package desktop for macOS (arm64 + x64)
bun run dist:win         # Package desktop for Windows x64
bun run fix              # Lint + format (Biome auto-fix)
bun run typecheck        # TypeScript check across monorepo

Server App (apps/server)

bun run dev                   # Vite dev server (localhost:3000)
bun run build                 # Production build -> .output/
bun run compile               # Compile to standalone binary (current platform)
bun run compile:darwin        # Compile for macOS (arm64 + x64)
bun run compile:darwin:arm64  # Compile for macOS arm64
bun run compile:darwin:x64    # Compile for macOS x64
bun run compile:linux         # Compile for Linux (x64 + arm64)
bun run compile:linux:arm64   # Compile for Linux arm64
bun run compile:linux:x64     # Compile for Linux x64
bun run compile:windows       # Compile for Windows (default: x64)
bun run compile:windows:x64   # Compile for Windows x64
bun run fix                   # Biome auto-fix
bun run typecheck             # TypeScript check

# Database (Drizzle)
bun run db:generate           # Generate migrations from schema
bun run db:migrate            # Run migrations
bun run db:push               # Push schema (dev only)
bun run db:studio             # Open Drizzle Studio

Desktop App (apps/desktop)

bun run dev                   # electron-vite dev mode (requires server dev running)
bun run build                 # electron-vite build (main + preload)
bun run dist                  # Build + package for current platform
bun run dist:linux            # Build + package for Linux (x64 + arm64)
bun run dist:linux:x64        # Build + package for Linux x64
bun run dist:linux:arm64      # Build + package for Linux arm64
bun run dist:mac              # Build + package for macOS (arm64 + x64)
bun run dist:mac:arm64        # Build + package for macOS arm64
bun run dist:mac:x64          # Build + package for macOS x64
bun run dist:win              # Build + package for Windows x64
bun run fix                   # Biome auto-fix
bun run typecheck             # TypeScript check

Testing

No test framework configured yet. When adding tests:

bun test path/to/test.ts              # Run single test file
bun test -t "pattern"                 # Run tests matching pattern

Code Style (TypeScript)

Formatting (Biome)

• Indent: 2 spaces | Line endings: LF
• Quotes: Single ' | Semicolons: Omit (ASI)
• Arrow parentheses: Always (x) => x

Imports

Biome auto-organizes. Order: 1) External packages → 2) Internal @/* aliases → 3) Type imports (import type { ... })

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { db } from '@/server/db'
import type { ReactNode } from 'react'

TypeScript Strictness

• strict: true, noUncheckedIndexedAccess: true, noImplicitOverride: true, verbatimModuleSyntax: true
• Use @/* path aliases (maps to src/*)

Naming Conventions

Type	Convention	Example
Files (utils)	kebab-case	auth-utils.ts
Files (components)	PascalCase	UserProfile.tsx
Components	PascalCase arrow	const Button = () => {}
Functions	camelCase	getUserById
Constants	UPPER_SNAKE	MAX_RETRIES
Types/Interfaces	PascalCase	UserProfile

React Patterns

• Components: arrow functions (enforced by Biome)
• Routes: TanStack Router file conventions (export const Route = createFileRoute(...))
• Data fetching: useSuspenseQuery(orpc.feature.list.queryOptions())
• Let React Compiler handle memoization (no manual useMemo/useCallback)

Error Handling

• Use try-catch for async operations; throw descriptive errors
• ORPC: Use ORPCError with proper codes (NOT_FOUND, INPUT_VALIDATION_FAILED)
• Never use empty catch blocks

Database (Drizzle ORM v1 beta + postgres-js)

• ORM: Drizzle ORM 1.0.0-beta (RQBv2)
• Driver: drizzle-orm/postgres-js (NOT bun-sql)
• Validation: drizzle-orm/zod (built-in, NOT separate drizzle-zod package)
• Relations: Defined via defineRelations() in src/server/db/relations.ts (contains schema info, so drizzle() only needs { relations })
• Query style: RQBv2 object syntax (orderBy: { createdAt: 'desc' }, where: { id: 1 })

export const myTable = pgTable('my_table', {
  id: uuid().primaryKey().default(sql`uuidv7()`),
  name: text().notNull(),
  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
})

Environment Variables

• Use @t3-oss/env-core with Zod validation in src/env.ts
• Server vars: no prefix | Client vars: VITE_ prefix required
• Never commit .env files

Dependency Management

• All versions centralized in root package.json catalog field
• Workspace packages use "catalog:" — never hardcode versions
• Internal packages use "workspace:*" references

Development Principles

These principles apply to ALL code changes. Agents MUST follow them on every task.

1. No backward compatibility — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case".
2. Always sync documentation — When code changes, immediately update all related documentation (AGENTS.md, README.md, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
3. Forward-only migration — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.

Critical Rules

DO:

• Run bun run fix before committing
• Use @/* path aliases (not relative imports)
• Include createdAt/updatedAt on all tables
• Use catalog: for dependency versions
• Update AGENTS.md and other docs whenever code patterns change

DON'T:

• Use npm, npx, node, yarn, pnpm — always use bun / bunx
• Edit src/routeTree.gen.ts (auto-generated)
• Use as any, @ts-ignore, @ts-expect-error
• Commit .env files
• Use empty catch blocks catch(e) {}
• Hardcode dependency versions in workspace packages
• Leave docs out of sync with code changes

Git Workflow

1. Make changes following style guide
2. bun run fix - auto-format and lint
3. bun run typecheck - verify types
4. bun run dev - test locally
5. Commit with descriptive message

Directory Structure

.
├── apps/
│   ├── server/           # TanStack Start fullstack app
│   │   ├── src/
│   │   │   ├── client/   # ORPC client + TanStack Query utils
│   │   │   ├── components/
│   │   │   ├── routes/   # File-based routing
│   │   │   └── server/   # API layer + database
│   │   │       ├── api/  # ORPC contracts, routers, middlewares
│   │   │       └── db/   # Drizzle schema
│   │   └── AGENTS.md
│   └── desktop/          # Electron desktop shell
│       ├── src/
│       │   ├── main/
│       │   │   └── index.ts       # Main process entry
│       │   └── preload/
│       │       └── index.ts       # Preload script
│       ├── electron.vite.config.ts
│       ├── electron-builder.yml   # Packaging config
│       └── AGENTS.md
├── packages/
│   └── tsconfig/         # Shared TS configs
├── biome.json            # Linting/formatting config
├── turbo.json            # Turbo task orchestration
└── package.json          # Workspace root + dependency catalog

See Also

• apps/server/AGENTS.md - Detailed TanStack Start / ORPC patterns
• apps/desktop/AGENTS.md - Electron desktop development guide