Duolith docs

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}"
    }
  ]
}
SettingDefaultIs
projectthe workspace folderThe folder holding pages/
port4321Where duolith dev serves
path/The address opened first
cliPaththe duolith.path settingThe duolith command
browserPaththe first Chrome or Chromium installedThe browser to start
headlessfalseRun 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:

EditorConfigurationTo 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
ZedThe 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.