AGENTS.md · Kong/insomnia

Sections

1. Tech Stack
2. Strict Rules
3. Command Output
4. Validation Commands
5. Worktree Setup
6. Repository Structure
7. Data Model Hierarchy
8. Key Patterns
9. Sensitive Data

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

## Tech Stack

- **UI:** React with React Router (loaders/actions pattern)
- **Components:** React Aria Components
- **Desktop Shell:** Electron (main + renderer processes)
- **Styling:** TailwindCSS
- **Language:** TypeScript
- **Database:** NeDB (`@seald-io/nedb`) — embedded NoSQL
- **Build/Dev:** Vite, npm workspaces monorepo

_See `package.json` for current versions and `.nvmrc` for the Node version._

## Strict Rules

- **No unsolicited formatting.** Rely on ESLint/Prettier. Do not reformat existing code.
- **Strict scoping.** Only modify code directly related to the prompt. Do not refactor adjacent code unless asked.

## Command Output

Prefer quiet command variants to minimise output volume:

- `git log --oneline -20` not `git log`
- `git diff --stat` not `git diff`
- `npm test --silent` not `npm test`
- `tsc --noEmit 2>&1 | head -50` for type-check failures
- Use the `Read` tool with `limit` rather than `cat` on large files
- Use `Grep` with `head_limit` rather than unrestricted searches

## Validation Commands

Run from repo root before considering work complete:

```bash
npm run lint          # ESLint all workspaces
npm run type-check    # TypeScript check all workspaces
npm test              # Tests all workspaces (or: npm test -w packages/insomnia)
```

## Worktree Setup

- New git worktrees may not have `node_modules` yet. Before installing or validating, switch to the repo's required runtime from the worktree root:

```bash
fnm use "$(cat .nvmrc)"
node -v
npm -v
```

- This repo expects the `.nvmrc` Node version and npm 11+. If `fnm` is unavailable, manually use an equivalent Node/npm version before running any `npm` commands.
- After switching versions in a fresh worktree, install dependencies from repo root with `npm ci`.
- Do **not** use `npm ci --ignore-scripts` for normal worktree setup. It leaves Electron partially installed, which later breaks builds, renderer import checks, and other validation commands.

## Repository Structure

`packages/`
  `insomnia/`                ← Main Electron app
    `src/`
      `common/`              ← Shared utils, settings types
      `routes/`              ← React Router files (clientLoader/clientAction)
      `ui/`                  ← React components, hooks, `insomnia-fetch.ts`
      `main/`                ← Electron IPC handlers, `preload.ts`
      `account/`             ← Auth, session, encryption
      `sync/`                ← Git/VCS sync
      `network/`             ← Request execution engine
      `templating/`          ← Nunjucks rendering (Web Worker)
  `insomnia-data/`           ← Data models, services, NeDB implementation, shared data utilities
  `insomnia-api/`            ← Cloud API client
  `insomnia-inso/`           ← CLI tool
  `insomnia-testing/`        ← Test framework

## Data Model Hierarchy

Organization
  → Project (local | remote/cloud | git-backed)
    → Workspace (scope: 'collection' | 'design')
      → Base Environment (auto-created: use `models.environment.getOrCreateForParentId(workspaceId)`)
        → Sub-Environments
      → Cookie Jar (auto-created)
      → Request Group (folders)
        → Request (HTTP, GraphQL, gRPC, WebSocket, Socket.IO)
      → Request (can be direct child of workspace)
**Note:** A Workspace with `scope: 'collection'` IS the collection.

## Key Patterns

- **Route-Based Actions:** Mutations use React Router's `clientAction` (`src/routes/`).
  - **CRITICAL:** `clientAction` blocks navigation. For long-running UI operations, use plain async functions instead.
- **Database Buffering:** Always buffer bulk writes (`database.bufferChangesIndefinitely()`, then `flushChanges()`). Unbuffered writes fire UI revalidation per operation, causing severe lag.
- **State Management:** Use Router loaders/actions and NeDB for persistent state. Use React `useState`/context for ephemeral UI state (No Redux/Zustand).
- **Electron IPC:** For main↔renderer communication, define handlers in `src/main/ipc/`, expose in `src/main/preload.ts`, and update `window.main` in `src/global.d.ts`.
- **Templates:** Nunjucks runs in a Web Worker (`src/templating/`). Use `{{ _.variable_name }}`.
- **Models:** Follow CRUD via `models.<type>` (e.g., `create()`, `update()`).
- **HTTP Calls:** Use `insomniaFetch()` for Insomnia backend APIs. Use plain `fetch()` for external/third-party APIs.
- **Styling:** Tailwind utility classes only. Use `clsx`/`tailwind-merge` for conditionals. Use React Aria for interactive HTML elements.
- **Testing:** Use **Vitest** (unit) and **Playwright** (E2E). Co-locate unit tests as `filename.test.ts`. Use `vi.mock()`. Prefer testing logic via loaders over mounting components.
- **E2E tests** live in `packages/insomnia-smoke-test/`. Full docs: [`packages/insomnia-smoke-test/README.md`](packages/insomnia-smoke-test/README.md).
- Run E2E from repo root: `npm run test:smoke:dev` (filter: `npm run test:smoke:dev -- <title-substring>`).
- New test imports: `import { test } from '../../playwright/test'` and `import { expect } from '@playwright/test'`.

## Sensitive Data

- **Vault system (AES-GCM):** For environment secrets (`EnvironmentKvPairDataType.SECRET`).
- **Electron safeStorage:** Platform-native encryption (`window.main.secretStorage`).