Skip to content

docs(repo): add cursor cloud dev environment instructions #9539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mikepitre wants to merge 1 commit into from
+11 −0
Closed

docs(repo): add cursor cloud dev environment instructions #9539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/cloud-dev-environment-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
9 changes: 9 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,12 @@ Clerk's JavaScript SDK and library monorepo.
- For the Mosaic design system (tokens, CVA utility, `MosaicProvider`, migration from existing system), see `references/mosaic-architecture.md`.
- For dev setup, testing, JSDoc/Typedoc, publishing, changesets, and commit conventions, see `docs/CONTRIBUTING.md`.
- For working in the repo day to day (setup ordering and footguns, the package map, dev-loop recipes, and the breaking-change checklist), the `clerk-monorepo` Claude Code skill in `.claude/skills/clerk-monorepo/` restates these rules in actionable form.

## Cursor Cloud specific instructions

Node/pnpm are already set up in the VM image; you do not need to install or activate anything. Node `24.15.0` is installed via nvm and made to win over the daemon's bundled `/exec-daemon/node` (v22) through symlinks in `/usr/local/cargo/bin` (which precedes `/exec-daemon` in `PATH`). Because the Cursor shell is non-interactive and does not source `~/.bashrc`, that symlink layer — not a profile edit — is what makes bare `node`/`pnpm`/`npx` resolve to v24 in every shell. If bare `node` ever reports v22, re-point those symlinks at `~/.nvm/versions/node/v24.15.0/bin`; do not edit `/exec-daemon`.

- Dependency install is handled by the startup update script (`pnpm install --frozen-lockfile`). Standard build/test/lint/dev commands live in `docs/CONTRIBUTING.md` and the `clerk-monorepo` skill; run `pnpm build` before `dev`/tests since packages consume each other's `dist/`.
- Runnable browser app: `pnpm dev:sandbox` serves the clerk-js UI sandbox at `http://localhost:4000` (it also starts the `@clerk/ui` bundle server on `:4011`, a hard dependency). No secrets needed — a staging publishable key is baked into `packages/clerk-js/sandbox/template.html`, so Clerk auth components render and talk to a live staging instance out of the box. Routes: `/sign-in`, `/sign-up`, `/user-profile`, etc. The Mosaic explorer (`pnpm dev:swingset`, `http://localhost:6006`) is a secondary secret-free app.
- Root `pnpm lint` currently exits non-zero on a clean checkout for reasons unrelated to environment setup: `scripts/lint.mjs` runs `turbo lint -- --quiet`, and `--quiet` gets appended to packages whose `lint` chains `typecheck` (e.g. `@clerk/headless` → `tsc --noEmit --quiet`), which TypeScript `6.0.3` rejects; there are also pre-existing eslint errors under `scripts/` and `integration/`. To lint a package's tooling cleanly, use `pnpm turbo lint --filter=<pkg>` (no `--quiet`).
- `pnpm test:integration:*` (Playwright E2E) needs 1Password-sourced `INTEGRATION_INSTANCE_KEYS` and live Clerk instances; it cannot run in this environment without those secrets. Unit tests (`pnpm test`, or `pnpm turbo test --filter=<pkg>`) run fully offline.
Loading