Debugging

Attach to running raclette service containers for plugin-focused backend debugging, or debug the raclette core monorepo while contributing to core-dev.

Core monorepo (core-dev contributors)

When working in the core-dev repository, debug configs live in the repo root so every contributor gets the same presets.

VS Code / Cursor

Open the core-dev folder as your workspace and use .vscode/launch.json.

Config	Use
CORE	Attach to the app/backend container (port 9229). Maps @raclettejs/core/services/backend ↔ /app.
[WB]: CORE	Attach to the workbench backend (port 9228).
CLI: dev [playground] / CLI: dev [Workbench]	Launch and step through the raclette CLI locally.
CLI: :dev [all], CLI: build […], CLI: down […]	Other root yarn/CLI workflows from launch.json.

Attach (Docker): enable backend debugging in your dev app config (services.backend.enableDebug: true or debugPort in raclette.config.js / YAML), run yarn :dev, then attach with CORE or [WB]: CORE.

Debug the CLI: use a CLI: preset to run Node on the raclette dev / build entry and set breakpoints under @raclettejs/core/src/.

See also the meta guide INSTALLATION.md — Debugging with VS Code / Cursor.

Neovim

The same presets are committed as .nvim/dap.lua (mirrors launch.json). Config names and ports match VS Code: CORE, [WB]: CORE, CLI: variants, etc.

Your Neovim setup must load project-local DAP configs and register the Node debug adapter:

1. nvim-dap — DAP client.
2. vscode-js-debug — same engine VS Code uses; install via Mason as js-debug-adapter or equivalent.
3. A config provider that reads {project}/.nvim/dap.lua (returns a function (root) -> configs) or falls back to .vscode/launch.json.

Typical workflow:

1. Start the dev stack with debug enabled (yarn :dev).
2. Set breakpoints in TypeScript or Vue sources.
3. Run your editor’s “pick debug configuration” command and choose CORE (9229) or [WB]: CORE (9228), or a CLI: config for local runs without Docker.

If your config does not load .nvim/dap.lua, use .vscode/launch.json with a launch.json-aware DAP setup instead (many nvim-dap setups support this via dap.ext.vscode).

Minimal .nvim/dap.lua contract

The file must live at the repository root and export either a list of configs or a function:

return function(root)
  return {
    {
      name = "CORE",
      type = "pwa-node",
      request = "attach",
      port = 9229,
      localRoot = vim.fs.joinpath(root, "@raclettejs/core/services/backend"),
      remoteRoot = "/app",
      sourceMaps = true,
    },
  }
end

Use type = "pwa-node" (or ensure your adapter aliases node → js-debug).

App and Workbench attach profiles

When debugging your app’s backend plugins (not the core monorepo itself), attach to the running app or workbench container and map local plugin folders to the mounted paths inside the container.

{
  "name": "[APP]",
  "type": "node",
  "request": "attach",
  "port": 9229,
  "address": "localhost",
  "restart": true,
  "sourceMaps": true,
  "localRoot": "${workspaceFolder}/plugins",
  "remoteRoot": "/app/src/appPlugins",
  "skipFiles": ["<node_internals>/**"],
  "outFiles": ["${workspaceFolder}/**/*.js"],
  "resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"]
}

{
  "name": "[WB]",
  "type": "node",
  "request": "attach",
  "port": 9228,
  "address": "localhost",
  "restart": true,
  "sourceMaps": true,
  "localRoot": "${workspaceFolder}/workbench/plugins",
  "remoteRoot": "/app/src/workbenchPlugins",
  "skipFiles": ["<node_internals>/**"],
  "outFiles": ["${workspaceFolder}/**/*.js"],
  "resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"]
}

Notes

• App backend debug port: 9229.
• Workbench backend debug port: 9228.
• Map local plugin folders to the mounted container paths for correct source mapping.
• Open the repository root (or ensure your editor resolves ${workspaceFolder} to it) so localRoot / remoteRoot paths match.