Skip to main content
Version: v4.23

Debugging With VS Code

VS Code offers a streamlined debugging experience that can be started with a single click when using launch configurations.

If you're unfamiliar with using the VS Code debugger in general, please visit the VS Code debugger documentation for a primer.

Requirements for Debugging​

In order for a debugger to function, the Stencil project must be configured to generate source maps for the compiled web components back to the source code. As of Stencil v3, source maps are generated by default, but be sure to double-check the project's Stencil config does not disable this behavior. More information regarding source maps in Stencil can be found in the project configuration documentation.

Debugging Stencil Components In a Web App​

It's a common use case to want to step through a web component's code as it executes in the browser and VS Code makes that process simple. Combining the debugger with Stencil's dev server in watch mode will allow you to debug changes as they're made.

Configuring the VS Code Debugger​

To debug Stencil components as they run in a browser (web app), create (or edit) the .vscode/launch.json file with the following configuration:

.vscode/launch.json
{
  ...,
  "configurations": [
    ...,
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome against localhost",
      "url": "http://localhost:3333",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "*": "${webRoot}/*"
      }
    }
  ]
}
note

If your Stencil project is within a monorepo structure, you may want (or need) to add the webRoot option to the above config to point to the Stencil project's directory. For instance, if you have your Stencil project at /packages/stencil-library, you would add the following to the config:

{
    ...,
    "webRoot": "${workspaceFolder}/packages/stencil-library",
}

This will create a configuration to open a Chrome debugger instance on port 3333 (the default port used by the Stencil dev server). To use this configuration, start a Stencil dev server (running npm start in a Stencil component starter project) and then run the configuration from the VS Code debugger tab. At this point, any breakpoints set in the component source code will pause browser execution when hit.

note

If your Stencil project is configured to use a different port for the dev server, you will need to update the url property in the debugger configuration with the correct port.

Debugging Static Site Generation (SSG)​

Static Site Generation, also known as prerendering, executes your components at build time to generate a snapshot of the rendered styles and markup to be efficiently served to search engines and users on first request.

Since this step runs in a Node.js process instead of a browser, debugging can't be done directly in the browser. However, debugging is straightforward using existing Node.js debugging techniques.

Overview​

The stencil build --prerender command will first build the hydrate script for a NodeJS environment, then prerender the site using the build. For a production build this is probably ideal.

However, while debugging you may not need to keep rebuilding the hydrate script, but you only need to debug through the prerendering process. Stencil creates a file in dist/hydrate that is used to actually execute your components.

To only prerender (and avoid rebuilding), you can use the stencil prerender dist/hydrate/index.js command, with the path to the script as a flag.

Tips for Debugging Prerendering​

By default, prerendering will start by rendering the homepage, find links within the homepage, and continue to crawl the entire site as it finds more links. While debugging, it might be easier to not crawl every URL in the site, but rather have it only prerender one page. To disable crawling, set the prerender config crawlUrls: false.

Next, you can use the entryUrls config to provide an array of paths to prerender, rather than starting at the homepage.

Additionally, console logs that are printed within the runtime are suppressed while prerendering (otherwise the terminal would be overloaded with logs). By setting runtimeLogging: true, the runtime console logs will be printed in the terminal. Below is an example setup for prerender debugging:

prerender.config.ts
import { PrerenderConfig } from '@stencil/core';

export const config: PrerenderConfig = {
  crawlUrls: false,
  entryUrls: ['/example'],
  hydrateOptions: (_url) => {
    return {
      runtimeLogging: true,
    };
  },
};

Configuring the VS Code Debugger​

To debug the Stencil prerender process, create (or edit) the launch.json file with the following configuration:

launch.json
{
  ...,
  "configurations": [
    ...,
    {
      "type": "node",
      "request": "launch",
      "name": "Prerender",
      "args": [
        "${workspaceFolder}/node_modules/@stencil/core/bin/stencil",
        "prerender",
        "${workspaceFolder}/dist/hydrate/index.js",
        "--max-workers=0",
        "--config=${workspaceFolder}/stencil.config.ts"
      ],
      "protocol": "inspector"
    }
  ]
}

This creates a new debugging configuration using the script that hydrates the app. We're starting up the stencil prerender command, and providing it a path to where the hydrate script can be found. Next we're using --max-workers=0 so we do not fork numerous processes to each of your CPUs which will make it difficult to debug.

Contents

Edit this page