feat(build): Add UMD support #40

GordonSmith · 2020-01-14T07:56:12Z

Use rollup.js to bundle each package and add UMD support.
Use terser to provide minimized packages.

Signed-off-by: Gordon Smith gordonjsmith@gmail.com

GordonSmith · 2020-01-14T08:00:08Z

Notes:

The bundled packages include any CSS which was directly imported by the sources
The "build" step is now actually two steps:
- Compile TS files to JS with ES6 compatible modules (./lib/ used to contain commonjs modules)
- Bundle ES6 modules into single UMD + single ES6 packages
Each package includes the sources from "tslib", it might be preferable to have them as a dependency (instead of a devDependency)?

(Now that I type this I suspect the "watch" scripts will need a tweak)

blink1073 · 2020-01-14T15:50:40Z

Hi @GordonSmith, thank you for pushing on this, but I think it over-complicates our build chain. Most other libraries produce either CommonJS or ES6. I think we will switch to ES6 when we switch to 2.0 libraries across the board.

GordonSmith · 2020-01-14T17:01:52Z

From a front end (Web Browser) developers perspective I would have to disagree (phosphor didn't "just work" like most of the UI libs I have used). I would go as far as saying that I am struggling to think of any Browser UI library that only ship as as a commonjs or es6 library!

While its not a big deal for myself as I have already gone through the exercise of creating a UMD shim for phosphor (https://github.com/hpcc-systems/Visualization/tree/master/packages/phosphor-shim), it was certainly bit of a pain at the time and is the type of thing that will put off some potential users... (IMO)

I could re-work the PR so that the added build steps are only needed during the "publish" pipeline if you like - but if your not interested that's ok as well...

saulshanabrook · 2020-01-15T17:50:53Z

Hey @GordonSmith, thanks for putting in this pr!

We chatted about this at our dev meeting this week and we had some questions about this change. None of us are all that familiar with UMD, but we do want to make it easy for folks to consume lumino! Would you be able/interested to come to our meeting next week to walk us through some of these changes? https://github.com/jupyterlab/team-compass/#weekly-developer-meeting

One question I had is if we could ship the UMD support separately, so we could keep shipping the original lib directory for downstream users (maybe keeping it as commonjs instead of es6?) and then also shipping the UMD stuff you generate with rollup?

GordonSmith · 2020-01-15T19:30:01Z

I am GMT based so if the meeting is at a reasonable hour here I should be able to make it...

While you could create a @jupyterlab/lumino-umd project / npm package, no one really does that anymore (as all the tooling pretty much just works these days)

In this PR there are basically two packages created

UMD (a convention which is commonjs / AMD / IIFE friendly)
ES6 (the "modern" format)

Which are exposed in package.json via:

main -> dist/index.js (UMD)
module -> dist/index.es6.js (ES6)

Now I could change that so "main" points at lib/index.js and ensure its the same as it is today. While also including the ES6 / UMD support, your package.json will look like this:

main -> lib/index.js (CommonJS)
module -> dist/index.es6.js (ES6)
browser -> dist/index.js (UMD)

Who will that affect?

Straight up NodeJS folks - nothing changes
Older WebPack users will default to the "main" entry point (no change).
Newer WebPack users will default to the "module" entry point (its the preferred format for WebPack these days)
IIFE folks will use the UMD version (will need some manual intervention)
AMD folks will use the UMD version (may need some manual intervention)
Other bundlers (RollupJS etc.) will use the module entry point

Which is still an improvement - but I suspect you fall into the "newer WebPack users" category so you will get hit with the change?

Finally it is worth noting that this PR didn't touch any of the WebPack / Karma test folders (which was a very conscious decision) as I hoped it would help "prove" that the bundled UMD (dist/index.js) was syntactically the same as the loose files in lib/* (with a slightly opinionated inclusion of the default CSS files...)

saulshanabrook · 2020-01-29T16:31:34Z

Sorry I forgot to reply with the meeting time. It's in half an hour if you can join https://github.com/jupyterlab/team-compass/#weekly-developer-meeting

GordonSmith · 2020-01-30T08:30:20Z

@saulshanabrook I am travelling this week (so only seeing this message now) - next week should work, do you have a Date / GMT time so I can get into a calendar?

afshin · 2020-01-30T09:35:06Z

@GordonSmith Our next call will be on Wednesday, 5 February at 17:00 GMT: https://calpoly.zoom.us/my/jupyter

Thanks!

afshin · 2020-02-05T17:55:02Z

packages/application/rollup.config.js

@@ -0,0 +1,35 @@
+import nodeResolve from 'rollup-plugin-node-resolve';
+import sourcemaps from "rollup-plugin-sourcemaps";
+import postcss from "rollup-plugin-postcss";


Purely cosmetic and it probably didn't get picked up because this is .js instead of .ts, but the Lumino convention is for strings to be single quotes, please.

GordonSmith · 2020-02-06T08:10:43Z

@afshin PR updated with:

IIFE example
AMD example
SourceMap support (debug the IIFE example and step into any of the lumio code and it should resolve all the way back to the TS files now)
Double quotes replaced with single quotes.

blink1073 · 2020-02-10T21:10:23Z

examples/example-dockpanel-amd/index.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>


I'm wary of adding the other examples since they aren't TS and they can easily get out of date.

Having them non TS is actually a good thing IMO (and why I went out of the way to convert them - including IE support).
While they shouldn't break for any minor/point releases they can certainly be added to the suite of tests (to check they load without warning) - I will look into this today?

Further Note: Once lumino has UMD support, then these types of examples work well in things like Gist, ObservableHQ and any online JS editor (the include paths will need to point to jasdelivr or unpkg or some other CDN server).

👍 to including these with tests.

@blink1073 you would think that would have been easy - ended up rolling my own with puppeteer

telamonian

There's a potential issue with the additions of "sourceMap": true to the various tsconfig files

telamonian · 2020-02-11T00:03:27Z

packages/domutils/tsconfig.json

 {
  "compilerOptions": {
    "composite": true,
+    "sourceMap": true,


Won't we also need something like "inlineSources": true,? Otherwise, won't we just run into the same issue as in #41 again?

Related: I've experimented extensively with various combinations of the typescript and webpack source map config options. I found that when using both "sourceMap" and "inlineSources", you also end up needing to set "sourceRoot". Otherwise, you run the very real risk of ending up with 15 indistinguishable index.ts files next to each other at the root of the inferred filesystem of your bundle (ie what you see in the left panel on the "sources" tab of devtools), which makes debugging a real pain. Ideally you want the source files to all be appropriately sorted in their respective @lumino/whatever dirs.

However, I was never able to find the "correct" value to use for "sourceRoot". For one thing, when building Lumino packages as part of Jupyterlab's build, the effect of "sourceRoot" seems to change depending on whether you do do a dev mode build or just the regular app build. Do you have any insight into the issue, @GordonSmith?

In this case it should be fine as the source maps get bundled as part of the rollup (and minification) processes (including the es6 module which webpack uses).

I will do a sanity check on one of the WebPack tests today.

Re the sourceRoot setting - So far I have never had to use this setting in any of my projects...

telamonian · 2020-02-11T00:06:38Z

packages/domutils/tsconfig.json

+    "sourceMap": true,
    "declaration": true,
+    "declarationDir": "./types",
+    "declarationMap": true,


What's the significance of moving the typings into a new separate dir? What exactly does "declarationMap" do here?

This is a slightly opinionated change to avoid generating code into the same folder as the sources.
It works as the package.json has a "types" property specifically to point to the new location.
declarationMap is analogous to sourceMap but for declaration files.

declarationMap is mostly useful for:

when you are linking locally (e.g. yarn link). With it, if you try to follow a lumino type to its declaration from lab source code, and lumino is linked locally, you will go to the source file, not the typings file.

if you distribute the TS source with the package, you will be able to do the above also for non-linked cases.

GordonSmith · 2020-02-11T10:11:26Z

One more observation WRT WebPack + Source Maps - the following configuration should "just work":

module.exports = {
    entry: './src/index.js',
    devtool: "source-map",
    output: {
        path: path.join(__dirname, "dist"),
        filename: 'index.min.js',
        library: "quickstart"
    },
    module: {
        rules: [
            { test: /\.js$/, use: ["source-map-loader"], enforce: "pre" }
        ]
    }
}

And does indeed work fine on my similar projects. But isn't quite working as expected in the Lerna configuration + examples folder (the source maps don't resolve all the way to the TS files).

I am pretty sure this is because of the way Lerna is hoisting and symlinking the libraries, but once it is released and consumed via "normal" npm mechanism it will just work (and something I will be testing with a RC release).

kinow · 2020-02-22T03:40:21Z

Don't have a lot of experience with UMD, but I think the current code deployed to NPM cannot be used directly in unpkg, and I think with UMD that would be possible (I'm trying to write a codepen with a Vue.js example and struggling to find a way to import Lumino modules). If so, +1 to adding UMD support

GordonSmith · 2020-02-22T13:12:15Z

@kinow yup this will solve that issue - FWIW I would recommend jsdelivr over unpkg, but both should work.

blink1073

These changes look good, thanks!

I'd prefer to wait and merge this until after we have a JupyterLab 2.0 stable release.
Then we can merge this, bump versions, and try it out in JupyterLab master for a bit before committing.

kinow · 2020-02-26T21:01:34Z

Sounds good to me @blink1073. Happy to help testing it once merged and a UMD version has been uploaded somewhere 👍

jasongrout · 2020-02-26T21:12:24Z

Thanks again everyone (and especially @GordonSmith) for working on this. I think it's a really valuable contribution.

jasongrout · 2020-05-12T20:21:32Z

We now have a stable JupyterLab 2.0 release, so I'd like to propose merging this again (looks like a conflict needs to be resolved at this point).

Use rollup.js to bundle each package and add UMD support. Use terser to provide minimized packages. Signed-off-by: Gordon Smith <gordonjsmith@gmail.com>

Fixed sourceMap support Include TS sources for sourceMap resolution Replaced " with ' in all rollup.config.js instances Signed-off-by: Gordon Smith <gordonjsmith@gmail.com>

GordonSmith · 2020-05-13T05:45:00Z

@jasongrout rebased and conflict resolved.

blink1073 · 2020-05-13T09:42:43Z

blink1073 · 2020-05-13T09:42:54Z

Thanks @GordonSmith!

tgeorgeux mentioned this pull request Jan 15, 2020

Weekly Dev Call Meeting Minutes 2020-1-15 jupyterlab/frontends-team-compass#36

Closed

tgeorgeux mentioned this pull request Jan 29, 2020

Weekly Dev Call Meeting Minutes 2020-1-22 jupyterlab/frontends-team-compass#37

Closed

afshin reviewed Feb 5, 2020

View reviewed changes

tgeorgeux mentioned this pull request Feb 5, 2020

Weekly Dev Call 2020-02-05 jupyterlab/frontends-team-compass#39

Closed

3 tasks

GordonSmith force-pushed the UMD branch from d052854 to b0a71ec Compare February 6, 2020 07:45

GordonSmith force-pushed the UMD branch 4 times, most recently from 666f4ac to 2f6b885 Compare February 6, 2020 09:54

blink1073 reviewed Feb 10, 2020

View reviewed changes

telamonian suggested changes Feb 11, 2020

View reviewed changes

GordonSmith force-pushed the UMD branch from 2f6b885 to be65bfb Compare February 12, 2020 13:24

blink1073 approved these changes Feb 26, 2020

View reviewed changes

GordonSmith added 2 commits May 13, 2020 06:36

feat(build): Add UMD support

c5570fd

Use rollup.js to bundle each package and add UMD support. Use terser to provide minimized packages. Signed-off-by: Gordon Smith <gordonjsmith@gmail.com>

chore(build): Added IIFE example (with IE compatibility)

c66e402

Fixed sourceMap support Include TS sources for sourceMap resolution Replaced " with ' in all rollup.config.js instances Signed-off-by: Gordon Smith <gordonjsmith@gmail.com>

GordonSmith force-pushed the UMD branch from be65bfb to c66e402 Compare May 13, 2020 05:43

blink1073 merged commit 90dd837 into jupyterlab:master May 13, 2020

blink1073 mentioned this pull request May 13, 2020

Task: Test UMD Approach Against JupyterLab #72

Closed

This was referenced May 23, 2020

Add sourcemaps back to original TS #76

Open

Update phosphor aliases jupyterlab/jupyterlab#8498

Merged

github-actions bot locked as resolved and limited conversation to collaborators Aug 18, 2022

Uh oh!

feat(build): Add UMD support #40

feat(build): Add UMD support #40

Uh oh!

Conversation

GordonSmith commented Jan 14, 2020

Uh oh!

GordonSmith commented Jan 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blink1073 commented Jan 14, 2020

Uh oh!

GordonSmith commented Jan 14, 2020

Uh oh!

saulshanabrook commented Jan 15, 2020

Uh oh!

GordonSmith commented Jan 15, 2020

Uh oh!

saulshanabrook commented Jan 29, 2020

Uh oh!

GordonSmith commented Jan 30, 2020

Uh oh!

afshin commented Jan 30, 2020

Uh oh!

afshin Feb 5, 2020

Choose a reason for hiding this comment

Uh oh!

GordonSmith commented Feb 6, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blink1073 Feb 10, 2020

Choose a reason for hiding this comment

Uh oh!

GordonSmith Feb 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GordonSmith Feb 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blink1073 Feb 11, 2020

Choose a reason for hiding this comment

Uh oh!

GordonSmith Feb 12, 2020

Choose a reason for hiding this comment

Uh oh!

telamonian left a comment

Choose a reason for hiding this comment

Uh oh!

telamonian Feb 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GordonSmith Feb 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

telamonian Feb 11, 2020

Choose a reason for hiding this comment

Uh oh!

GordonSmith Feb 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vidartf Feb 12, 2020

Choose a reason for hiding this comment

Uh oh!

GordonSmith commented Feb 11, 2020

Uh oh!

kinow commented Feb 22, 2020

Uh oh!

GordonSmith commented Feb 22, 2020

Uh oh!

blink1073 left a comment

Choose a reason for hiding this comment

Uh oh!

kinow commented Feb 26, 2020

Uh oh!

jasongrout commented Feb 26, 2020

GordonSmith commented Jan 14, 2020 •

edited

Loading

GordonSmith commented Feb 6, 2020 •

edited

Loading

GordonSmith Feb 11, 2020 •

edited

Loading

GordonSmith Feb 11, 2020 •

edited

Loading

telamonian Feb 11, 2020 •

edited

Loading

GordonSmith Feb 11, 2020 •

edited

Loading

GordonSmith Feb 11, 2020 •

edited

Loading