🚀 Feature: ability to debug the running package code

[johnnyreilly]

Bug Report Checklist

• [X] I have tried restarting my IDE and the issue persists.
• [X] I have pulled the latest main branch of the repository.
• [X] I have searched for related issues and found none that matched my issue.

Overview

I love being able to debug. Whenever I'm making a package I try to set up a way to debug the code in VS Code. Either using a combo of tsc / sourcemaps and Node.js or using ts-node.

I think it'd be awesome if CTA had this built in. I'd be potentially up for contributing this. My instinct would be to prefer using just tsc / sourcemaps and Node.js to avoid adding another dependency.

What do you think?

Additional Info

N/A

[johnnyreilly]

Got a rough version working locally in VS Code. Implementation looks like this:

launch.json file:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": ["<node_internals>/**"],
            "program": "debug/index.js",
            "preLaunchTask": "build:debug"
        }
    ]
}

task.json file:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "npm",
            "script": "debug",
            "problemMatcher": [],
            "label": "build:debug",
            "detail": "Build a debug version of the project"
        }
    ]
}

The scripts of package.json has a new entry:

        "debug": "rimraf debug && tsc --noEmit false --outDir debug",

And requires a dev dependency of rimraf to delete the debug folder prior to debug builds.

With the above in place, you can F5 in VS Code and debug, hitting your breakpoints. Is this an implementation that would work well generally?

[JoshuaKGoldberg]

Hmmm. Hmm... I' really prefer not to add to package.json or take on new directories for builds. Is there a way to reuse the existing tsup builder (pnpm build) instead?

[johnnyreilly]

Yeah I think so - given that the tsup config has 2 key settings set we're actually in a decent position:

import { defineConfig } from "tsup";

export default defineConfig({
    bundle: false,
    clean: true, // WILL CLEAN DIRECTORY PRIOR TO BUILD MEANING WE DON'T DEBUG STALE CODE
    dts: true,
    entry: ["src/**/*.ts"],
    format: "esm",
    outDir: "lib",
    sourcemap: true, // WILL ALLOW US TO DEBUG ORIGINAL SOURCE CODE
});

Given these are in place I think we might only need tasks.json

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "npm",
            "script": "build",
            "problemMatcher": [],
            "label": "build",
            "detail": "Build the project"
        }
    ]
}

and launch.json:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug Program",
            "skipFiles": ["<node_internals>/**"],
            "program": "lib/index.js",
            "preLaunchTask": "build"
        }
    ]
}

[JoshuaKGoldberg]

Awesome. Let's do it!

[johnnyreilly]

I'll put a PR together! Out of curiosity, what is the motivation for using tsup? I've read the docs and this:

https://jakeginnivan.medium.com/options-for-publishing-typescript-libraries-9c37bec28fe

But I'm not super clear on the benefits of using it over tsc. Is it about speed of compilation?

[JoshuaKGoldberg]

It's a few things:

• Speed of compilation, yes. It runs esbuild to generate .js files quickly. It also runs tsc when dts is enabled as in this repo.
• It also allows an array for format - which is nice in packages that need to dual-emit CJS and ESM. For my projects that's mostly packages such as https://github.com/JoshuaKGoldberg/ts-api-utils and https://github.com/JoshuaKGoldberg/eslint-plugin-expect-type used as or with ESLint plugins.
• The clean option is a nice one too.

Being able to do all that in a single tool run by a single pnpm run build is nice and straightforward. I like that!

[github-actions[bot]]

:tada: This is included in version v1.54.0 :tada:

The release is available on:

• GitHub releases
• npm package (@latest dist-tag)

Cheers! 📦🚀