Debugging a page
duolith dev gives every page, layout and component module a source map whose source is the .duo file itself, and the Duolith debug adapter uses it (decision 0069). Breakpoints go on lines of the page, stack traces name it, and signals show their values under the names you wrote. duolith build emits no maps.
In VS Code
With the Duolith extension installed, open the project folder and press F5. With no launch.json, VS Code debugs the folder's app: it starts duolith dev and Chrome. To keep the settings, add:
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug the app",
"type": "duolith",
"request": "launch",
"project": "${workspaceFolder}"
}
]
}
| Setting | Default | Is |
|---|---|---|
project | the workspace folder | The folder holding pages/ |
port | 4321 | Where duolith dev serves |
path | / | The address opened first |
cliPath | the duolith.path setting | The duolith command |
browserPath | the first Chrome or Chromium installed | The browser to start |
headless | false | Run the browser without a window |
Set a breakpoint on a line of a page's script block, such as const title = draft.trim(); in examples/control-flow/pages/index.duo, and do what runs it: type a todo and press Add. The debugger stops on that line of the .duo file. In Variables and on hover, draft shows "Debug me", not the state cell it compiles to. Step, continue and the debug console work as for any JavaScript; the page's console.log shows there too. Breakpoints in a page you have not opened yet are placed when it loads.
In other editors
The adapter is a plain DAP executable over stdio. Install it with npm install -g @duolith/debug-adapter, which puts duolith-debug-adapter on your PATH. From this repository, it is node packages/debug-adapter/dist/duolith-debug-adapter.cjs. Every editor passes the launch arguments above. The configurations in editors/ start duolith-debug-adapter from the PATH:
| Editor | Configuration | To start |
|---|---|---|
| Neovim (nvim-dap) | editors/others/neovim/lua/duolith/dap.lua: require("duolith.dap").setup() registers the adapter and a launch for ${workspaceFolder}. { adapter = { "node", "/path/to/duolith-debug-adapter.cjs" } } names another command, and { launch = { port = 4400 } } adds launch arguments. | :lua require("dap").continue() in a page |
| Helix | [language.debugger] in editors/others/helix/languages.toml, with an app template that asks for the project folder and port | :debug-start app |
| Zed | The dev extension in editors/others/zed gives the duolith debug adapter; debug_adapter_schemas/duolith.json lists its arguments. In .zed/debug.json: [{ "label": "Debug the app", "adapter": "duolith", "request": "launch" }] (the project defaults to the worktree) | debugger: start |
| JetBrains IDEs (LSP4IJ) | editors/jetbrains/dap/duolith/: a debug adapter template (template.json) and its launch configuration (launch.json). In Settings > Build, Execution, Deployment > Debugger > Debug Adapter Servers, add a server with these, then make a Debug Adapter Protocol run configuration for it. | Debug the run configuration |
editors/others/test/headless/debuggers.test.ts checks each one. It starts the command each configuration names from the PATH, then launches with that configuration's arguments: duolith dev and Chromium start for a copy of examples/minimal, and the adapter becomes ready for breakpoints. Neovim's configuration is read from Neovim itself. Zed and the JetBrains IDEs are not run, so the test fills in their project folder itself.
A crash from a phone
A native build's setup modules carry source maps back to their .duo files. The bundle step keeps the bundle's own maps beside it, in dist/maps/lynx/background.map. A crash report from a phone carries the stack as the engine printed it. To map it back to your lines, run:
node packages/engine/scripts/map-frames.ts dist-native/dist/maps/lynx/background.map < stack.txt
Each frame is printed with the place it maps to, such as pages/index.duo:20:3. A stack copied from Lynx for Web needs --lines-before 2, because it wraps the script and so shifts its lines.
With the browser's own debugger
The source maps work without the adapter too. VS Code's JavaScript debugger reads them:
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug the app (Chrome)",
"type": "chrome",
"request": "launch",
"url": "http://localhost:4321",
"webRoot": "${workspaceFolder}",
"preLaunchTask": "duolith dev"
}
]
}
// .vscode/tasks.json
{
"version": "2.0.0",
"tasks": [
{
"label": "duolith dev",
"type": "shell",
"command": "duolith dev",
"isBackground": true,
"problemMatcher": {
"pattern": { "regexp": "^error: (.*)$", "message": 1 },
"background": { "activatesOnStart": true, "beginsPattern": "duolith dev", "endsPattern": "http://localhost" }
}
}
]
}
webRoot is the project folder because the maps name each source from the project root (/pages/index.duo). Here a signal draft shows as its cell; read draft.value. In Chrome DevTools → Sources, the page files are listed under pages/, layouts/ and components/ with their own text.