Vendoring uhtml in a project

marlun commented 3 months ago

I would like to vendor uhtml in my project which is a JavaScript esm project but which uses JSDoc and tsc to get type hinting in my editor.

What I would like is something like uhtml.bundle.js and uhtml.d.ts so that I can have something like (some parts removed for brevity):

/**
 * @typedef { import("src/vendor/uhtml").Hole } Hole
 */

import { html } from "../vendor/uhtml.esm.js";

/**
 * @type {(...) => Hole}
 */
export function HeaderView(...) {
  return html`
    <div>
      ...
    </div>
  `;
}

If I got to https://unpkg.com/uhtml it redirects to https://unpkg.com/uhtml@4.5.9/keyed.js which seems to give me the bundle for uhtml.bundle.js, even though I'm not sure why it's keyed.js?

Can I do something similar for all the types?

Also, thought I would be able to get something similar by running npm run build?

WebReflection commented 3 months ago

the way you use modules in your IDE is by installing these from npm ... in that case you'll have the source code and all dependencies and that source code will contain the JSDoc too, which is how types are defined/exported in here anyway.

If you want the full bundled and optimized code of any of the variants listed in the README you can use esm.run

https://esm.run/uhtml for the main / default export
https://esm.run/uhtml/keyed for the keyed export
https://esm.run/uhtml/reactive for the reactive export
... and so on ...

To have the source code with JSDoc in it from unpkg.com (watch out, it's a non maintained service) you can add ?module

https://unpkg.com/uhtml?module for the main / default export
https://unpkg.com/uhtml/keyed?module for the keyed export
... and so on ...

I hope this answers your questions.

WebReflection commented 3 months ago

P.S. I've just noticed unpkg is broken with non-index modules ... but then again, that service is done, you should not use it anyway. To have from the source via CDN everything you need you need to use an importMap that satisfies all dependencies and dependencies of dependencies but it's doable. I don't know how else to help there except check rollup exports for pre-bundled stuff but all of those are optimized for production.

You can solve your IDE problems with import type from uhtml though ... or something similar.

marlun commented 3 months ago

the way you use modules in your IDE is by installing these from npm ... in that case you'll have the source code and all dependencies and that source code will contain the JSDoc too, which is how types are defined/exported in here anyway.

Thanks, but unfortunately I'm not using npm. I have an interest in no-build setups and I'm trying to keep the complexity as low as possible.

https://esm.run/uhtml for the main / default export https://esm.run/uhtml/keyed for the keyed export https://esm.run/uhtml/reactive for the reactive export ... and so on ...

All those outputs starts with severals chunks like `import t from"/npm/udomdiff@1.1.0/+esm"; which would need to be bundled for me to be able to use it.

I know this might not bee the usual setup and that it would be easily solved by either using npm or fetching directly from a cdn (require network) or just vendoring the source code (unbundled). I'll have to look into playing with rollup, esbuild, tsc and similar tools to get what I'm looking for I think 😊

marlun commented 3 months ago

Adding the following almost gets me where I want except I'm getting errors in the JSDoc in the outfile because they use things like * @param {import("./literals.js").Cache} info

  {
    plugins: [nodeResolve()],
    input: "./esm/index.js",
    output: {
      file: "./esm/bundle.js",
      format: "es",
    },
  },

WebReflection commented 3 months ago

yeah, the production code is inevitably JS ... you want some sort of limbo between the source code and the production one and I am not sure how to help there ... the unpkg first link should work though but it's not one file ... it can't be one file ... not sure there is a rollup plugin for what you need there.

marlun commented 3 months ago

OK, so I think I've landed in just using the esm index.js I get when I run npm run build and then don't use the typescript types because I only used Hole and I can get that from index.js and use it in my JSDoc. I don't get the description but I doesn't have important information when developing with it anyway 😊

Sorry for being a little annoying 😇

WebReflection / uhtml

Vendoring uhtml in a project #127