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 Rindo project must be configured to generate source maps for the compiled web components back to the source code. As of Rindo v3, source maps are generated by default, but be sure to double-check the project's Rindo config does not disable this behavior. More information regarding source maps in Rindo can be found in the project configuration documentation.

Debugging Rindo 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 Rindo's dev server in watch mode will allow you to debug changes as they're made.

Configuring the VS Code Debugger

To debug Rindo 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 Rindo project is within a monorepo structure, you may want (or need) to add the webRoot option to the above config to point to the Rindo project's directory. For instance, if you have your Rindo project at /packages/rindo-library, you would add the following to the config:

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

This will create a configuration to open a Chrome debugger instance on port 3333 (the default port used by the Rindo dev server). To use this configuration, start a Rindo dev server (running npm start in a Rindo 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 Rindo 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 rindo 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. Rindo creates a file in dist/hydrate that is used to actually execute your components.

To only prerender (and avoid rebuilding), you can use the rindo 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 '@rindo/core';

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

Configuring the VS Code Debugger

To debug the Rindo 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/@rindo/core/bin/rindo",
        "prerender",
        "${workspaceFolder}/dist/hydrate/index.js",
        "--max-workers=0",
        "--config=${workspaceFolder}/rindo.config.ts"
      ],
      "protocol": "inspector"
    }
  ]
}

This creates a new debugging configuration using the script that hydrates the app. We're starting up the rindo 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.