JavaScript Debugger

From a compatible code editor you can set breakpoints in your Lens script, step through it line by line, and inspect the call stack and variables — in a Lens Studio preview panel or on a SPECS device.

Tip: In addition to using the debugger with your code editor, you can have CLAD drive the debugger for you with the /lens-js-debugger skill — or just by asking the AI to "use the debugger". See Agents and Skills for the full set.

Compatibility

You can attach an external JavaScript debugger to the following targets:

• A SPECS device
• Certain Lens Studio preview panel types:
  • SPECS 27
  • No Simulation
  • Horizontal

Supported JS debug clients:

• VS Code
• Cursor
• Other VS Code forks

Usage

1. Open the same project in Lens Studio and VS Code.

2. Navigate to the Run and Debug tab in VS Code.

   

3. Press Attach to running Lens (Lens Studio).

   

4. Select the target to attach from the list.

   

   If there is a single target, the debugger attaches to it automatically.

5. Enjoy a proper debugging experience — pause on breakpoints, explore the call stack, watch variables, and more.

   

Important Considerations

• The debugger attaches to a Lens that is already running. To hit a breakpoint in onAwake or in top-level JS, follow these steps:
  1. Attach to running Lens (Lens Studio).
  2. Set your breakpoints.
  3. Reload the Lens while keeping the debugger attached.
  4. The JS engine reruns all the scripts from the very beginning and hits your breakpoints.
• Stepping over await statements is not supported by the JS engine. The workaround is to set a breakpoint on the next line and resume.
• The debugger only navigates to JS sources located in the Assets directory. To debug a package, you'll have to unpack it for editing.
• The Stop Preview button on a Preview panel toolbar is not a debugger pause — the two should not be confused.
• Switching to a different workspace in Lens Studio ends all current Preview panels' debug sessions.
• If VS Code presents a list of targets to attach and you click elsewhere, the list is dismissed and the debugger attaches to all targets at once. That's a VS Code quirk with no workaround.
• Only one Lens Studio instance at a time is supported. If you launch another, it will not start the debug server (the port is taken by the first one).

SPECS-specific Considerations

• Important: you must use the Send to SPECS for Debugging option.

  

• The normal Send to SPECS flow sends optimized bytecode instead of JS, with no debug info available.

• It is not currently possible to reload a Lens on SPECS while keeping the debug session alive, so the workflow for debugging onAwake / top-level JS is only supported in Preview panels.

• When paused in the debugger, expanding the Global scope (which is huge) and jumping between stack frames frequently may, very rarely, drop the connection between Lens Studio and SPECS.

We will release more debug capabilities in upcoming versions of Lens Studio and SnapOS. Stay tuned!