Issue description

I would like to have Visual Studio Code to hint autocompletion and provide documentation for a JavaScript project which includes libraries a module in a separate HTML file.

Context

I am using P5JS. It assumes we include the P5JS library and our script via the <script src="…"> tag in an HTML file. Autocompletion and documentation work after installing the p5.vscode extension. So, no problem here.

I am also using ml-matrix, which I'm including in the HTML via the <script src="…"> tag. The library constructors and methods can be accessed via mlMatrix.. (I figured this by toying around in the console, and I wouldn't know otherwise how to find out I need to prepend mlMatrix. to all functions in the library.)

index.html

<head>
    <!-- script src="…" P5JS libraries -->
    <script src="./node_modules/ml-matrix/matrix.umd.js"></script>
</head>
<body>
    <script src="./script.js"></script>
</body>

script.js

A = mlMatrix.Matrix.eye(3)  // no autocompletion or docs, code runs
console.log(A)

Workaround

Adding import * as mlMatrix from "ml-matrix" to the beginning of script.js makes autocompletion and documentation work, but the overall project does not run. So, I have to comment and uncomment the first line every time I save and preview my edits on the browser.

script.js

import * as mlMatrix from "ml-matrix"

A = mlMatrix.Matrix.eye(3)  // autocompletion and docs work, code doesn't run
console.log(A)

When loading the HTML, the browser complains with script.js:1 Uncaught SyntaxError: Cannot use import statement outside a module..

Desiderata

I'd like to be able to save and preview my project while having a working autocompletion and documentation hint from VSC.

Debugging

After reading a few sections of David Flanagan's «JavaScript: The Definitive Guide», I started figuring out what's going on. So, I'm reporting here my current understanding.

JavaScript, or rather ECMAScript, used to be a scripting language. Scripts loaded with <script src="…"> are "global" scripts, living on the current page, injecting vars and functions in the global scope (or window object).

In order to support proper software engineering relying on modularity, modules were introduced in 2015, in ECMAScript 6, or ES6 in short. To import a module in an HTML document one can use <script type="module" src="…">.

Now, to import a module in a JS file, the file itself needs to be a module. So, dealing with an actual script myself, I cannot do such a thing.

Even by <script src="…"> a module, it won't inject itself in the main namespace. It will create a whatever name where it will store everything it exports. So, now we are at the point where we need to instruct the IDE that a module has been loaded on the HTML side with a specific name and it's used in a JS script.

So, we have now a more articulate question.

Issue re-statement

How to inform VSC that a module has been loaded through the HTML page?

I believe a probable answer will include some custom jsconfig.json to be created. Right now I have zero clues about how to do this.

Another solution would be using some specific ///<reference path="…"/> at the beginning of the JS file. Also for this I have no specific knowledge.