JSDoc intellisense when using script tags

Question

Problem

I am finding that JSDoc works well with intellisense and type checking when the JSDoc-typed code is "inside" the project; however, including a JSDoc-typed library via a script tag (<script src="mylibrary.js">) does NOT provide any intellisense, type checking, or hints.

My intention is to publish a library with types included, and I had hoped that JSDoc would allow me to do that even for users who wanted to include the script via tag rather than installing and importing with NPM, where a .d.ts file would suffice.

I appreciate any insight anyone can provide.

Assumptions

My guess is that the TypeScript checker can't access code included in a script tag, even if that script is local, but since I have seen nothing that outright states that, I wanted to check my understanding here. I'm a TypeScript user but am new to JSDoc, so I may be missing some nuance here.

Details

I am using VSCode with Microsoft's "JavaScript and TypeScript Nightly" plugin.

My library code works something like this:

/**
 * @preserve
 * @typedef {object} LibObj - The main library object
 * @property {string} LibObj.name - The name of the library
 */
globalThis.LibObj = {
  name: "My Library's Name"
}

When I include the library code into my HTML page, LibObj and LibObj.name have an any type and I get no intellisense.

Answer 1

It is quite straightforward. Assuming Visual Studio Code environment.

If your intended usage for users is they will have page.html with

<script src="mylibrary.js"></script><!-- your library -->
<script src="script.js"></script><!-- their script using your library -->

then you should instruct them to add triple slash directive

/// <reference path="mylibrary.js" />

at the beginning of their script.js, optionally along with // @ts-check comment directive and perhaps //@module JSDoc directive.

This way the language server will know for sure what library.js provides and include it in the intellisense and type checking in the script.js.

---

Fig:

library.js:

/**
 * @preserve
 * @typedef {object} LibObj - The main library object
 * @property {string} LibObj.name - The name of the library
 */
/** @type {LibObj} */
globalThis.LibObj = {
  name: "My Library's Name"
}

script.js:

/// <reference path="library.js" />

LibObj.

Having cursor at the end of the script.js and asking for suggestions yields: