Onboarding: hoppscotch/hoppscotch

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 45%)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Hoppscotch is an open-source API development ecosystem (alternative to Postman/Insomnia) that runs on Web, Desktop (via Tauri/Rust), and CLI. It supports REST, GraphQL, WebSocket, SSE, Socket.IO, and MQTT request testing with real-time responses, collections, environments, and team collaboration. The self-hosted backend (NestJS + Prisma + PostgreSQL) enables on-premises deployment with auth, team workspaces, and history. Monorepo under packages/: hoppscotch-common holds shared Vue 3 UI components and core logic, hoppscotch-selfhost-web and hoppscotch-sh-admin are the deployable frontends, hoppscotch-backend is the NestJS/Prisma API server, and hoppscotch-desktop wraps everything in Tauri (Rust). Shared libraries include @hoppscotch/data (schema/types), @hoppscotch/ui (design system), and codemirror-lang-graphql (custom CodeMirror extension).

Who it's for

API developers and backend engineers who need a privacy-conscious, self-hostable alternative to Postman—especially teams on-prem or air-gapped who cannot use SaaS tools. Also open-source contributors familiar with Vue 3 + TypeScript monorepos wanting to add protocol support or UI features.

Maturity & risk

Hoppscotch is highly mature and production-ready: it's at v3.0.1, has active CI via .github/workflows/ (tests, docker releases, desktop/agent builds), uses commitlint + husky for enforced commit standards, and the changelog and CODEOWNERS indicate a multi-maintainer team. The dependency list, Docker Compose deploy config, and Caddy reverse-proxy configs signal real enterprise deployment usage.

The monorepo has heavy dependency surface across pnpm workspaces including NestJS, Prisma, Vue 3, Tauri (Rust), and multiple pnpm overrides patching vulnerabilities (e.g. ws, lodash, cross-spawn)—keeping these in sync is non-trivial. The project uses pnpm@10.33.2 strictly enforced via only-allow pnpm, so npm/yarn users will be blocked. Firebase is still referenced (firebase.json, firestore.rules) alongside the self-hosted backend, indicating a partially migrated dual-backend architecture that can confuse new contributors.

Active areas of work

Active work is visible in the GitHub Actions workflows for building the Hoppscotch Agent (.github/workflows/build-hoppscotch-agent.yml) and Desktop (.github/workflows/build-hoppscotch-desktop.yml), indicating the Tauri-based desktop and a new agent binary are under active development. The package.json has a generate-ui script and pnpm workspace structure suggesting ongoing design system extraction.

Get running

git clone https://github.com/hoppscotch/hoppscotch.git cd hoppscotch cp .env.example .env # fill in required vars pnpm install pnpm dev

Daily commands:

All packages in dev mode:

pnpm dev

Production build:

pnpm generate

Serve built selfhost-web:

pnpm start

Docker Compose (full stack with DB):

docker compose up

Map of the codebase

• packages/hoppscotch-agent/src-tauri/Cargo.toml — Defines the Rust/Tauri agent's dependencies and build configuration — the backbone of the desktop/CLI proxy that intercepts and forwards HTTP requests bypassing CORS.
• packages/hoppscotch-agent/package.json — Entry point for the Tauri-based desktop agent package, defining scripts, dependencies, and the build pipeline for the cross-platform native app.
• package.json — Root monorepo manifest orchestrating all packages via pnpm workspaces; defines top-level scripts for dev, build, lint, test, and code generation across the entire ecosystem.
• docker-compose.yml — Defines the full self-hosted stack (frontend, backend, database, email) — critical for understanding how all services are wired together in production.
• firestore.rules — Defines Firestore security rules governing all data access — any contributor touching auth or persistence must understand these rules to avoid data leaks.
• .github/workflows/tests.yml — CI pipeline that runs all tests and checks across packages — understanding this is required before submitting PRs to know what gates must pass.
• packages/codemirror-lang-graphql/src/index.js — Core of the custom CodeMirror GraphQL language extension used across the editor UI — changes here affect all GraphQL query editing experiences.

How to make changes

Add a new Docker service to the self-hosted stack

1. Define the new service in the development compose file, specifying image, environment variables, ports, and depends_on relationships. (docker-compose.yml)
2. Mirror the service definition with production-ready settings (resource limits, restart policies) in the deploy compose file. (docker-compose.deploy.yml)
3. Add a reverse proxy route for the new service in the multiport Caddy configuration. (aio-multiport-setup.Caddyfile)
4. Add the service health check endpoint to the healthcheck script so Docker knows when the service is ready. (healthcheck.sh)

Add a new Tauri native capability to the desktop agent

1. Declare the new capability identifier and its scope in the Tauri capabilities manifest so the frontend webview is granted permission. (packages/hoppscotch-agent/src-tauri/capabilities/default.json)
2. Implement the Rust command handler using #[tauri::command] and register it in the Tauri builder in the main Rust source. (packages/hoppscotch-agent/src-tauri/Cargo.toml)
3. Add the new Rust dependency (if needed) to the agent's crate manifest. (packages/hoppscotch-agent/src-tauri/Cargo.toml)
4. Update the agent's JS package scripts if new build steps are required for the capability. (packages/hoppscotch-agent/package.json)

Add a new GraphQL syntax rule to the CodeMirror extension

1. Extend the Lezer grammar file with the new syntax rule, token definition, or production — following the existing grammar conventions. (packages/codemirror-lang-graphql/src/syntax.grammar)
2. Update the index.js to export any new language facets, completions, or linting rules derived from the grammar change. (packages/codemirror-lang-graphql/src/index.js)
3. Bump the package version and verify the rollup build config still correctly bundles the grammar and JS together. (packages/codemirror-lang-graphql/rollup.config.js)

Add a new Firestore collection with access rules

1. Write match rules for the new collection, specifying which authenticated users can read/write, following the existing allow/deny patterns. (firestore.rules)
2. Add any composite indexes required for queries on the new collection fields. (firestore.indexes.json)
3. Register the rules and indexes with the correct Firebase project alias. (.firebaserc)

Why these technologies

• Tauri (Rust) — Provides a lightweight, secure native desktop shell around the web UI, enabling system-level HTTP requests that bypass browser CORS restrictions — critical for an API testing tool.
• pnpm workspaces — Manages a multi-package monorepo (web app, desktop agent, CodeMirror extension, CLI) with strict dependency isolation and fast, disk-efficient installs.
• Firebase / Firestore — Offers zero-ops real-time sync for user collections, environments, and history in the cloud-hosted variant without requiring a custom backend from the open-source team.
• Docker Compose + Caddy — Enables one-command self-hosted deployment with automatic HTTPS via Caddy, making it accessible to teams that cannot use the cloud-hosted version.
• CodeMirror 6 (Lezer grammar) — Provides a performant, extensible editor with first-class support for custom language grammars, enabling rich GraphQL/HTTP editing experiences in the browser.
• Vue 3 + Vite — Delivers fast HMR during development and tree-shaken production bundles for the web and desktop UIs, with a component model that fits the feature-heavy Hoppscotch UI.

Trade-offs already made

• Dual deployment model: cloud Firebase + self-hosted Docker
  • Why: Maximizes reach
  • Consequence: undefined

Traps & gotchas

1. pnpm is strictly enforced via preinstall: npx only-allow pnpm — using npm or yarn will hard-fail. Must use pnpm@10.33.2. 2. The .env.example must be populated before dev; the backend needs DATABASE_URL (PostgreSQL), JWT secrets, and optionally SMTP/OAuth credentials — missing these causes silent auth failures. 3. Firebase config (firebase.json, .firebaserc) is still present but the self-hosted path uses the NestJS backend — running both simultaneously causes endpoint conflicts. 4. The Rust toolchain is required if building the desktop app or agent — not needed for web-only development. 5. pnpm dev starts all packages concurrently via -r do-dev; individual packages can be started from their own directories to reduce noise.

Architecture

Concepts to learn

• Tauri (Rust-based desktop shell) — The desktop app uses Tauri instead of Electron, meaning the Rust toolchain is required and the IPC model differs significantly from web — critical for desktop contributors
• Server-Sent Events (SSE) — Hoppscotch supports SSE as a protocol alongside WebSocket — understanding the unidirectional push model is needed to work on or test that feature
• pnpm Workspaces — The entire repo is a pnpm monorepo with inter-package dependencies resolved via workspace: protocol — understanding hoisting and workspace linking is essential for adding or modifying packages
• CodeMirror 6 Language Extensions — The custom codemirror-lang-graphql package implements a CodeMirror 6 language mode — contributing to editor features requires understanding the Lezer parser system and CM6 extension API
• Prisma ORM with PostgreSQL — The NestJS backend uses Prisma for all DB access including migrations — any schema change requires running prisma migrate and regenerating the client, a non-obvious multi-step process
• GraphQL Code Generation — The repo uses graphql-codegen (pnpm gen-gql) to emit typed query/mutation hooks from the backend schema — frontend GraphQL calls are type-safe and generated, not hand-written
• MQTT Protocol — Beyond REST/GraphQL/WebSocket, Hoppscotch implements MQTT client support — a pub/sub protocol common in IoT that has very different connection semantics from HTTP-based APIs

Related repos

• Kong/insomnia — Direct alternative: open-source API client (REST/GraphQL/gRPC) that Hoppscotch is frequently compared to
• usebruno/bruno — Another open-source Postman alternative with offline-first, git-friendly approach — same target user base
• hoppscotch/hoppscotch-backend — The backend was historically a separate repo before monorepo consolidation — older issues/PRs may reference it
• nickvdyck/nvd.code-browser — Not directly related, but Tauri-based desktop app pattern used similarly to hoppscotch-desktop
• supabase/supabase — Comparable self-hosted open-source SaaS alternative architecture (monorepo, Docker Compose deploy, NestJS-style backend) that Hoppscotch contributors often reference for deployment patterns

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow for Rust/Tauri build validation of hoppscotch-agent

The repo has .github/workflows/build-hoppscotch-agent.yml but the packages/hoppscotch-agent/src-tauri directory contains a full Rust/Tauri project with a Cargo.lock. There is no dedicated CI workflow that runs cargo check, cargo clippy, or cargo test on PRs targeting the agent package. Adding this would catch Rust compile errors and linting issues before they reach main, especially since the agent is a security-sensitive component (it proxies API requests from the desktop app).

• [ ] Inspect packages/hoppscotch-agent/src-tauri/Cargo.lock and packages/hoppscotch-agent/src-tauri/.cargo/config.toml to understand the Rust toolchain version and any cross-compilation targets already configured
• [ ] Create .github/workflows/ci-hoppscotch-agent.yml that triggers on pull_request with paths: ['packages/hoppscotch-agent/**']
• [ ] Add steps: actions/checkout, dtolnay/rust-toolchain@stable, Swatinem/rust-cache pointing at packages/hoppscotch-agent/src-tauri, then cargo clippy -- -D warnings and cargo test inside that working directory
• [ ] Add a tauri-action dry-run step (with --no-bundle) so the full Tauri build graph is validated without producing release artifacts
• [ ] Update CONTRIBUTING.md with a note that agent changes require the Rust toolchain and reference the new workflow

Add unit tests for the custom CodeMirror GraphQL language package (codemirror-lang-graphql)

The packages/codemirror-lang-graphql package ships a hand-written Lezer grammar (src/syntax.grammar) and an entry point (src/index.js) but has no test files whatsoever. The grammar is a critical piece of the GraphQL editor experience; regressions in token parsing are silent and hard to spot in integration. Adding unit tests using @lezer/generator test utilities would directly improve stability of the editor for all users and is a well-scoped, self-contained task for a new contributor.

• [ ] Read packages/codemirror-lang-graphql/src/syntax.grammar to understand which GraphQL constructs (queries, mutations, fragments, directives, variables) are tokenised
• [ ] Add @lezer/generator and @codemirror/lang-test (or the standard Node test runner) as devDependencies in packages/codemirror-lang-graphql/package.json
• [ ] Create packages/codemirror-lang-graphql/src/syntax.grammar.test.js covering: valid query documents, mutation syntax, fragment definitions, inline fragments, variable declarations with types, and directive usage
• [ ] Add a do-test script entry in packages/codemirror-lang-graphql/package.json consistent with the root workspace test script (pnpm -r do-test)
• [ ] Verify the new tests run via pnpm test from the repo root and add a note in the package README.md about how to run them locally

Refactor and document the multi-port vs sub-path Caddy AIO setup configuration files

The repo contains two Caddyfile variants (aio-multiport-setup.Caddyfile and aio-subpath-access.Caddyfile) and a launcher script (aio_run.mjs), but the README.md and CONTRIBUTING.md contain no explanation of when or how to use either file, and there is no schema-validation or lint step for these Caddyfiles in CI. Operators deploying self-hosted

Good first issues

1. Add missing unit tests for protocol helpers in packages/hoppscotch-common/src/helpers/ — the test script exists (pnpm test) but coverage for WebSocket/SSE helpers is likely thin given the file structure. 2. The codemirror-lang-graphql package (packages/codemirror-lang-graphql/) has no visible test files — adding a test suite with example GraphQL schema completion cases would be a clean, self-contained contribution. 3. The TRANSLATIONS.md exists but translation completeness tooling is absent — a script that diffs locale files against the base English locale and reports missing keys would be immediately useful.

Top contributors

• @jamesgeorge007 — 30 commits
• @mirarifhasan — 17 commits
• @CuriousCorrelation — 10 commits
• @nivedin — 6 commits
• @anwarulislam — 3 commits

Recent commits

• cbb32d1 — fix(cli): ship semver as a runtime dependency (#6257) (jamesgeorge007)
• 7036ab5 — fix(common): preserve string contract for GQL history responses (#6244) (jamesgeorge007)
• aee017c — fix(common): subfolder add-new in team collections respects write access (#6243) (nivedin)
• 50f16e2 — fix(common): set domain url as mockserver environment (#6185) (nivedin)
• c4e1f02 — fix(backend): harden onboarding config endpoint (#6240) (mirarifhasan)
• f344d4e — chore(common): add token_refresh auth event and harden no-sync flag (jamesgeorge007)
• 3073d15 — chore(agent): bump version to v0.1.17 (jamesgeorge007)
• 078d710 — chore: security patch for the dependency chain v2026.4.0 (#6191) (mirarifhasan)
• 96ceb84 — fix(desktop): unified store scope and migration reroute (#6238) (CuriousCorrelation)
• df97d11 — fix(common): restore magic-link sign-in flow on cloud for orgs (#6237) (jamesgeorge007)

Security observations

• Critical · Hardcoded Weak Default Database Credentials in Example Config — .env.example. The .env.example file contains a hardcoded default PostgreSQL password 'testpass' (DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch). Operators may deploy with these defaults without changing them, exposing the database to unauthorized access. Combined with potential open port exposure in Docker Compose, this is a critical risk. Fix: Remove example credentials entirely or replace with a clearly invalid placeholder (e.g., 'YOUR_STRONG_PASSWORD_HERE'). Enforce password complexity requirements in deployment documentation. Add validation in startup scripts that reject default/weak credentials.
• Critical · Weak or Placeholder DATA_ENCRYPTION_KEY in Example Config — .env.example. The DATA_ENCRYPTION_KEY in .env.example is set to 'data encryption key with 32 char', a human-readable placeholder that is exactly 32 characters. Operators who deploy without changing this value will have all sensitive database-stored data encrypted with a known, publicly visible key, effectively providing no encryption protection. Fix: Replace the placeholder with a cryptographically random 32-character key generated via a secure method (e.g., openssl rand -hex 16). Add a startup check that validates the key is not the default placeholder value and fails loudly if it is.
• High · Potential Sensitive Data Exposure via .env Files in Repository — .envrc, .env.example. The presence of .env.example alongside .envrc in the repository root increases the risk that actual .env files containing real credentials could be accidentally committed. The .envrc file (used by direnv) may contain environment variable exports that could expose secrets if not properly gitignored or if developers misconfigure their workflow. Fix: Ensure .env, .env.local, .env.production, and similar files are listed in .gitignore. Audit .envrc to ensure it only sources .env files and does not directly contain secret values. Consider using a secrets manager (Vault, AWS Secrets Manager) instead of file-based secrets for production deployments.
• High · lodash Version Override May Indicate Known Vulnerability Dependency Chain — package.json (pnpm.overrides). The pnpm overrides section pins lodash to '4.18.1', which appears to be a non-standard version (the actual latest stable 4.x is 4.17.21). This could be a typo (4.18.1 does not exist as a stable release) which may result in resolution failures or fallback to an older vulnerable version. Lodash has had multiple high-severity prototype pollution vulnerabilities (CVE-2019-10744, CVE-2020-8203, CVE-2021-23337) in versions prior to 4.17.21. Fix: Verify the intended lodash version. If the goal is to pin to the latest secure 4.x version, use '4.17.21'. Run 'pnpm audit' to confirm no known vulnerabilities remain in the dependency tree after correction.
• High · X-Forwarded-For Header Trust Configuration Risk — .env.example. The .env.example contains a comment about 'the client's IP address is understood as the left-most entry in the X-Forwarded' (truncated), suggesting a TRUST_PROXY or similar setting. If improperly configured, this allows attackers to spoof their IP address by injecting X-Forwarded-For headers, bypassing IP-based rate limiting, access controls, or audit logging. Fix: Ensure the TRUST_PROXY setting is explicitly configured to trust only specific known reverse proxy IP ranges rather than blindly trusting all X-Forwarded-For values. Document the required network topology and validate proxy trust settings in the deployment guide.
• High · WHITELISTED_ORIGINS Contains Broad localhost Entries — .env.example. The WHITELISTED_ORIGINS variable in .env.example whitelists multiple localhost ports (3170, 3000, 3100) and custom protocol origins. If this default is carried into production deployments without modification, it could allow unintended origins to interact with the backend via CORS, potentially enabling CSRF or unauthorized API access from locally running attacker-controlled pages. Fix: Production deployments should set WHITELISTED_ORIGINS to only the specific production domain(s). Add validation logic that warns or fails if localhost origins are present in a non-development environment.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.