Project editor profile

Maintain a single manifest (.editor/profile.json) and generate editor files that VS Code, Cursor, and VSCodium all understand. Keeps extensions/plugins scoped to the stack instead of loading every global install.

Example in this repo: .editor/profile.json → run pnpm editor:sync.

Layout

.editor/
  profile.json           # Project manifest (stack, extensions, cursor plugins, settings)
  defaults.settings.json # Shared baseline merged into every project
.vscode/                 # Generated — commit to git
  settings.json
  extensions.json
.cursor/                 # Generated — commit to git
  hooks.json             # workspaceOpen → load-workspace-plugins.mjs
scripts/
  sync-editor-profile.mjs   # Regenerate .vscode + .cursor/hooks.json
  load-workspace-plugins.mjs  # Hook: emit pluginPaths from profile

Workflow checklist

- [ ] 1. Detect stack (package.json, configs, test runners)
- [ ] 2. Edit .editor/profile.json (extensions, cursor.plugins, settings overrides)
- [ ] 3. Run: pnpm editor:sync (or node scripts/sync-editor-profile.mjs)
- [ ] 4. Reload window; accept recommended extensions when prompted
- [ ] 5. Confirm Cursor plugins load (hooks) or install missing marketplace plugins
- [ ] 6. Commit .editor/, .vscode/, .cursor/hooks.json

Step 1: Detect stack

Do not recommend extensions for stacks the repo does not use — reduces attack surface and UI noise (audit-ide-dependencies).

Step 2: Edit profile.json

Minimal shape:

{
  "name": "my-app",
  "stack": ["next", "typescript", "pnpm"],
  "extensions": {
    "recommend": ["dbaeumer.vscode-eslint"],
    "unwanted": ["rust-lang.rust-analyzer"]
  },
  "cursor": {
    "plugins": [
      { "name": "shadcn", "publisher": "cursor-public", "optional": true }
    ]
  },
  "settings": {
    "eslint.useFlatConfig": true
  }
}

• extensions.recommend → .vscode/extensions.json recommendations (VS Code/Cursor prompt to install).
• extensions.unwanted → unwantedRecommendations (discourage irrelevant global extensions).
• cursor.plugins → resolved under $CURSOR_HOME/plugins/cache/<publisher>/<name>/<hash>/ by load-workspace-plugins.mjs on workspaceOpen (Cursor hooks).
• settings → merged over .editor/defaults.settings.json into .vscode/settings.json.

Step 3: Generate

pnpm editor:sync
# or: node scripts/sync-editor-profile.mjs

Never hand-edit generated .vscode/settings.json long-term — change profile.json and re-sync.

Formatter / extension settings (important)

Cursor validates editor.defaultFormatter against installed extensions only. If ESLint is only recommended but not installed, use built-ins in profile.settings:

• vscode.typescript-language-features — TS/JS format
• vscode.json-language-features — JSON

Put extension-only keys in .editor/profile.extensions.json (merged by editor:sync only when that extension exists under ~/.cursor/extensions/). Example: Biome (biomejs.biome) for lint + format instead of ESLint.

Step 4: Good defaults (baseline)

defaults.settings.json already sets:

• 2-space indent, final newline, trim whitespace
• File nesting for package.json / lockfiles / configs
• TypeScript import preferences and move-update-imports
• Sensible git/terminal defaults

Override per project in profile.settings only when needed (e.g. eslint.useFlatConfig, Tailwind v4 experimental.configFile, Playwright reuse browser).

Override per project in profile.settings (e.g. Biome formatter, workspace TypeScript SDK, .next excludes, Tailwind v4 config path).

Step 5: Cursor vs VS Code

Optional: symlink agent skills into .cursor/skills/ or .agents/skills/ per your project's agent docs.

Step 6: New project / extend

1. Copy .editor/defaults.settings.json and scripts/sync-editor-profile.mjs, scripts/load-workspace-plugins.mjs.
2. Add "editor:sync": "node scripts/sync-editor-profile.mjs" to package.json.
3. Author .editor/profile.json from stack table above.
4. Run pnpm editor:sync and commit outputs.

For monorepos, use one profile at the root or per-package profiles with separate sync invocations (node scripts/sync-editor-profile.mjs from each package after adjusting paths — extend script if needed).

Anti-patterns

• Putting project-only settings in global Cursor settings.json
• Recommending every extension you personally use globally
• Hand-editing .vscode/settings.json without updating profile.json
• Listing Cursor plugins in profile.json that were never installed from the marketplace (use "optional": true or install first)
• Running npm audit fix inside ~/.cursor/extensions (audit-ide-dependencies)

Related skills

• audit-ide-dependencies — audit extension/plugin CVEs under ~/.cursor
• fix-dependency-security — project pnpm audit, SFW installs

References

• VS Code workspace settings
• Extension recommendations
• Cursor hooks — workspaceOpen
• Cursor plugins