Typescript Source Maps and VS Code Debugging

[keckelt]

Problem

While extensions can be built with TypeScript and any other bells and whistles, this requires two build steps:

1. tsc which compiles the TypeScript to JavaScript, and puts the results to lib folder
2. @jupyterlab/builder and its webpack than take the compiled files and bundles them.

For each step source maps can be generated that describe (i) how to map from the original TypeScript code to its JavaScript result, and (ii) how the JavaScript is then bundled. However, this process does not result in a source map from the bundled JavaScript to the TypeScript code. As a consequence, you can place breakpoints in the TypeScript files in VS Code, because it does not know how the Typescript file relate to the code in the bundles that are executed.

This was also discussed in Discourse previously.

Proposed Solution

To get a sourceMap for both steps I made the following steps:

1. Enable the generation of sourcemap files in tsconfig
   `"sourceMap": true,
2. Add the source-map-loader to my devDependencies
3. Create a custom rule to use it in webpack.config.js:

  module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: 'pre',
        use: ['source-map-loader']
      }
    ]
  }
};

4. Reference it in the package.json jupyterlab property (the @jupyterlab/builder will then merge it with its default config)

  "jupyterlab": {
    "extension": true,
    "outputDir": "loops/labextension",
    "webpackConfig": "webpack.config.js"
  }

With that in place, debugging in VS Code is rather straight forward, but I put my configuration below for completness.
This is for Firefox, using the Debugger for Firefox extension.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Firefox",
      "type": "firefox",
      "request": "launch",
      "reAttach": false,
      "url": "http://localhost:13013/lab?",
      "pathMappings": [
        {
          "url": "webpack://${workspaceFolderBasename}/",
          "path": "${workspaceFolder}/"
        }
      ],
      "webRoot": "${workspaceFolder}"
    }
  ]
}

Additional comments

I'm not sure if all of this should be part of the resulting cookiecutter template. The webpack part could probably be integrated in the builder and the cookiecutter just enabled sourceMaps for Typescript (and maybe a default debug config).

I'm happy to contribute a PR.

[welcome]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively.

You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[fcollonval]

Thanks @keckelt

Regarding the webpack configuration, you were beaten by @3coins who opens: jupyterlab/jupyterlab#13765

I'll push to get a release with it as soon as possible.

For vscode configuration, for now we are trying to not point to a dev tool rather than another. But there is one specifically for VSCode configuration there: https://github.com/jupyterlab/debug-config-cookiecutter

Personally, I would like to switch to a more powerful template library; in particular copier is pretty neat. The goal is to be able to get the template form to support feature like conditional parameters (to get a basic and advanced configuration for example). And another advantage of copier (in addition to support updates) is the ability to combine multiple templates. This sounds like a good pattern to separate pure JupyterLab extension configuration and for example IDE configuration.

If you want to help bringing this further, let me know.

[bollwyvl]

copier

Looks pretty rad. Cookiecutter has a lot of baggage and can't change much.

But, geez... another thing that's almost JSON schema, but not quite (e.g. github actions.yml).

Of one note: pushing out source maps can more than double the size of a package. This might be something someone needs to opt into, e.g. only during build:dev, for example.

[keckelt]

Regarding the webpack configuration, you were beaten by @3coins who opens: jupyterlab/jupyterlab#13765

Nice! what are the odds 😄

For vscode configuration, for now we are trying to not point to a dev tool rather than another. But there is one specifically for VSCode configuration there: https://github.com/jupyterlab/debug-config-cookiecutter

Makes sense. I've seen the cookiecutter but didn't really know how to apply it so I manually copied the config. The settings didn't work for me though.

[keckelt]

Closing this, as source maps generated by this PR: #278

Available with jupyterlab v3.6.0