Using umd globals with modules in a Typescript project

Question

I am trying to get the Leaflet library to play well with my Typescript project.

My project follows the commonJs pattern (imports\exports in my source files), but when I build with webpack, the compiler gives me the following errors from my files where I try to access an L global exposed by the leaflet module

'L' refers to a UMD global, but the current file is a module. Consider adding an import instead.

Now I can get around this if I import in leaflet into my source files as follows:

import * as L from 'leaflet'

But I was wondering if I could access t globally across all my files without having to have imports in each of my files.

I had a dig around and found some workarounds where you can declare your own globals like so:

globals.d.ts

import * as L from "leaflet";

declare global {
  const L: L
}
export {};

I'm not sure if this is recommended, it feels a bit of a dirty hack, is there a proper way with webpack config to provide globals exposed by UMD modules for a commonJs project, or am I talking nonsense? I admit I get confused trying to understand the differences between the module types and their interchangeability, so go easy on me!

Answer 1

In module you can import another modules or use globals. No way to import module to all your modules at once. If you are lazy to write import everywhere, then you should use global variable.

UMD module system is universal. If it is imported to some module (CommonJS, AMD...), then it behaves like module, i.e. it does not populate global scope. If you want UMD to become global, you should just add it as <script> to the page. Then you can use .d.ts. file to notify TypeScript, that leafet available in global scope. There is no any hack there (besides, using global scope instead of modules is a hack by itself nowaday).

Answer 2

I faced the same problem as Sam Claus in the comments. The error prevents me from easily referring to namespaces in Typescript which are provided by scripts that are loaded in script tags inside the HTML file.

My task was to make a simple static HTML report from some data using Plotly. I don't (want to) use a bundler because I didn't find it necessary at first. At the moment I use modules as individual files that are compiled from TS to JS and I load the entry module in a tag.

Plotly is imported in the classic way, the minified non-module version is loaded from a script tag in the HTML head, that I downloaded and stored locally. The static page can be used offline. Only for the type definitions, I use NPM. I avoid adding additional dependencies to the lock file by only using a locally stored minified version that I am not going to change. It is probably the most lightweight and fast technique that one could think of. I added "plotly.js" to the types options in the .tsconfig so that the namespace is available globally without import. As long as I compiled TS as a concatenation of classic scripts, I could make use of the Plotly namespace. The problem was, the concatenation order of the script pieces is not intelligently derived from file contents (besides new CORS issues during testing!). The order is fragile and not maintainable so that I turned the files into modules where import and export statements create an automatic order.

I found, there are two ways to bypass the error with UMD globals.

1. Using NPM to get the module version of the library and refer to the module via an import map in the HTML file. See question about importing Plotly with NPM for the typescript part. Will waste memory for the package manager. In case of very few dependencies, it might not matter because a new empty file itself might be bigger than the change of the package-lock.json.

2. Defining an alias variable.

   // @ts-ignore
   const plotly = Plotly
   

   The Advantage of the alias is that its usage does not generate errors. The usage of the "UMD global" is concentrated in only one place and therefore is easy to ignore. The disadvantage is the unnecessary variable which uses a slightly different name than the common namespace name (probably violating naming conventions).

   I only needed the import in one module and therefore put the above two lines under my import statements. But in general, all UMD globals can also be defined in and exported from an extra file using the // @ts-nocheck once at the beginning of the file to suppress all errors.

   Then, they can be imported on demand in other modules: import { plotly as Plotly } from "./dependencies.js"

   In theory, one could also default-export each from their own file. A new file plotly.js is created in the source directory:

   // @ts-ignore
   export default const plotly = Plotly
   

   which is imported as

   import * as Plotly from "./plotly.js"  // relative path to our own file
   

   But the increased number of files probably causes a higher waste in memory than just adding these dependencies with NPM.

It's a hack after all and it would be better if the TypeScript developers re-think the issue and turn the error into some kind of warning, particularly because it is not related to faulty behaviour and therefore should not be treated as an error.