Skip to main content

Debug a Lens With the JavaScript Debugger

Attach VS Code or Cursor to a Lens running in the Lens Studio Preview or on SPECS to set breakpoints, step through scripts, and inspect variables, or let CLAD drive the debugger.

  • Available on all platforms
Platform details: Snapchat, SPECS, Camera Kit Web, Camera Kit Mobile fully supported.

Platform details

  • Snapchat — Fully supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

From a compatible code editor you can set breakpoints in your Lens scripts, step through them line by line, and inspect the call stack and variables, in a Lens Studio Preview panel or on SPECS.

CLAD can drive the debugger for you: name the /lens-js-debugger skill in a prompt, or ask the assistant to use the debugger. See CLAD Agents and Skills for the other skills.

Where you can attach the JavaScript debugger

You can attach a debugger to:

  • A Lens running on SPECS.
  • A Lens Studio Preview panel set to SPECS 27, No Simulation, or Horizontal.

From these code editors:

  • VS Code
  • Cursor
  • Other editors based on VS Code

IntelliJ IDEA and WebStorm can attach to a Preview panel too; see External Debugger.

Attach the debugger to a running Lens

Lens Studio writes the debug configuration, Attach to running Lens (Lens Studio), into the project's .vscode/launch.json. It connects to Lens Studio on port 9222.

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

  2. In VS Code, open the Run and Debug view.

    The Run and Debug icon, a play triangle with a bug, in the VS Code activity bar
  3. Start Attach to running Lens (Lens Studio).

    The Run and Debug view with the Attach to running Lens (Lens Studio) configuration and its green start button
  4. Choose the Lens to attach to from the list: SPECS, or a Preview panel. With only one running Lens, the debugger attaches to it without asking.

    The list of running Lenses to debug, with a SPECS device and Preview 1
  5. Debug as you would any JavaScript: pause on breakpoints, explore the call stack, and watch variables.

    The VS Code debug toolbar with pause, continue, step over, step into, step out, restart, and disconnect

Debug a Lens on SPECS

To debug on SPECS, send the Lens with Send to SPECS for Debugging: select Preview Lens in the toolbar, then Send to SPECS for Debugging under Additional Settings. The regular Send to SPECS sends optimized bytecode instead of JavaScript, which has no debug information.

The Preview Lens on Device menu with the Send to SPECS card and Additional Settings, including Send to SPECS for Debugging

On SPECS:

  • You can't reload the Lens and keep the debug session, so catching breakpoints in onAwake or in top-level code (see the next section) works only in a Preview panel.
  • When you're paused in the debugger, expanding the large Global scope and switching often between stack frames can, rarely, drop the connection between Lens Studio and SPECS.

More debugging features are planned for future versions of Lens Studio and Snap OS.

Hit breakpoints in onAwake and top-level code

The debugger attaches to a Lens that is already running, so breakpoints in onAwake or in top-level script code aren't hit on the first run. In a Preview panel:

  1. Attach to the running Lens with Attach to running Lens (Lens Studio).
  2. Set your breakpoints.
  3. Reload the Lens, keeping the debugger attached.

The JavaScript engine reruns every script from the beginning and stops at your breakpoints.

Things to know about the JavaScript debugger

  • The JavaScript engine can't step over an await statement. Set a breakpoint on the next line and resume instead.
  • The debugger opens only JavaScript sources in the project's Assets folder. To debug code in a package, unpack the package for editing first.
  • The Stop Preview button on a Preview panel's toolbar is not a debugger pause.
  • Switching to another workspace in Lens Studio ends the debug sessions of all current Preview panels.
  • If VS Code shows the list of Lenses and you click elsewhere, the list closes and the debugger attaches to all of them at once. This is VS Code behavior, with no workaround.
  • Only one Lens Studio window at a time can host the debugger. A second instance can't start the debug server, because the first one is using its port.