exercism.typescript.vscode.debugger.md

Setting up VS Code Debugger for Exercism TypeScript

These instructions outline how to configure the VS Code debugger to work with your TypeScript Exercism exercises using ts-node.

1. Configure `.yarnrc.yml` for `node-modules`:

Ensure your .yarnrc.yml file in the root of your project has the following setting. If the file doesn't exist, create it.

nodeLinker: node-modules

This configuration is necessary because while Yarn's Plug'n'Play (PnP) feature can work with ts-node in some scenarios, it may cause issues when your project is set up to use ECMAScript modules (ESM). As noted in the ts-node issue (TypeStrong/ts-node#1709 (comment)), explicitly setting nodeLinker: node-modules ensures compatibility and avoids potential resolution problems when debugging with ts-node in an ESM context.

2. Install Dependencies:

Open your terminal in the root of your Exercism exercise directory and run the following commands:

corepack yarn install
corepack yarn add --dev tslib @types/node ts-node

corepack yarn install: Installs the project dependencies as specified in your package.json and yarn.lock file.
corepack yarn add --dev tslib @types/node ts-node: Installs the necessary development dependencies:
- tslib: A runtime library for TypeScript.
- @types/node: TypeScript type definitions for Node.js APIs.
- ts-node: Allows you to execute TypeScript files directly in Node.js.

3. Verify Execution (Optional):

You can test if ts-node is working correctly by running your TypeScript file directly:

node --loader ts-node/esm your-exercise-file.ts

Replace your-exercise-file.ts with the actual name of your TypeScript file (e.g., rna-transcription.ts).

4. Configure VS Code Debugger:

Go to the Run and Debug view in VS Code (click the bug icon in the Activity Bar).
If you don’t have a launch.json file yet, click "create a launch.json file".
Choose "Node.js" as the environment.
Replace the contents of the generated launch.json file with the following:

{
  "version": "1.0.0",
  "configurations": [
    {
      "name": "TS-Node",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "node",
      "runtimeArgs": [
        "--loader",
        "ts-node/esm"
      ],
      "program": "${file}",
      "cwd": "${workspaceRoot}",
      "internalConsoleOptions": "openOnSessionStart",
      "skipFiles": [
        "<node_internals>/**",
        "node_modules/**"
      ]
    }
  ]
}

Explanation of the configuration:

"name": "TS-Node": A descriptive name for your debug configuration.
"type": "node": Specifies that you are debugging a Node.js application.
"request": "launch": Tells VS Code to launch the program.
"runtimeExecutable": "node": Uses the system Node.js.
"runtimeArgs": ["--loader", "ts-node/esm"]: Uses ts-node to load .ts files as ESM modules.
"program": "${file}": Runs the currently opened file.
"cwd": "${workspaceRoot}": Uses the root of your project as the working directory.
"internalConsoleOptions": "openOnSessionStart": Opens the console when debugging starts.
"skipFiles": Avoids stepping through internal or library code.

5. Configure `tsconfig.json` for Source Maps

Make sure your tsconfig.json includes the following compiler option to enable source maps (which allow the debugger to link back to your original TypeScript source):

{
  "compilerOptions": {
    "sourceMap": true
  }
}

6. Start Debugging:

Open the TypeScript file you want to debug in VS Code.
Set breakpoints by clicking in the gutter next to line numbers.
Open the Run and Debug view.
Make sure "TS-Node" is selected in the dropdown.
Press F5 or click the green Start Debugging arrow.

blumus/exercism.typescript.vscode.debugger.md