Best practice for including non-Deno TypeScript libraries

[jaredkrinke]

What's the smoothest workflow for including/vendoring non-Deno TypeScript libraries that aren't tightly coupled to Node (e.g. jsonc-parser)?

Given these libraries aren't tightly coupled to Node, I thought this would be easy, but after reading and re-reading several sections of the Deno manual and searching the web, I'm still not seeing a great solution. Hopefully I just missed something obvious :)

The biggest issues I'm encountering are:

• Non-Deno TypeScript wants imports to not have ".ts" extension (whereas Deno requires an extension)
  • Obviously, this prevents everything from "just working"
• Finding/creating declaration (".d.ts") files is surprisingly difficult

Approaches I've considered

1. See if someone already ported the library to Deno and published it to deno.land/x

I don't like this solution because it inserts a random, untrusted contributor into the workflow. Note: for the Microsoft library example above, I'm fine with assuming Microsoft isn't doing anything nefarious, so I may not even look at all the code before using the module in my project.

2. Fork the library and add ".ts" to all imports

This works, and the only new contributor is myself, but it is tedious and feels like something I shouldn't have to do. It also means I have to potentially redo some or all of this tedious work when I want to upgrade the module (especially if the module has been refactored).

This could be automated, but a robust solution would probably have to use the TypeScript compiler API, which I hoped I'd never have to deal with.

Edit: one more annoyance with this approach: if the library I'm importing has 100 source files, now I have 100 imports. If someone's aware of a TypeScript bundler that works, that would be a huge help here.

3. Use a Node-to-Deno CDN

In practice, this hasn't worked well for me. The biggest issue is that the type declarations are often missing or incorrect. I'm also a bit paranoid about trusting these CDNs, especially when they send me unreadable, minified JavaScript.

I'm not sure if the "missing declarations" problem is because NPM packages usually don't include declaration files in their "main" package (and instead toss the types into a separate @types/ package, for good reason). Unhelpfully, I can't get "deno info" to tell me if types were provided at all (and I can't find any ".d.ts" files in my Deno cache).

4. Use WebPack/Rollup/esbuild

I don't have a lot of experience with these tools, but in every case, it looked like TypeScript declaration file support was bolted on with some random plugin that hasn't been updated in years.

As a particularly egregious example, WebPack's ts-loader plugin says to use declaration-bundler-webpack-plugin for delcarations which doesn't even provide a source code link on NPM.

Edit: maybe there's a Deno-focused/compatible bundler I missed?

5. Create an import map to add ".ts" extensions

This works, but import maps are an application-level concept, so I can't really use them for a library I plan to publish. At least this seems trivial to automate.

6. Just run tsc and copy all the ".js" and ".d.ts" files it produces

This probably works... as long as the tsconfig.json produces output compatible with Deno. I'm hoping there's a better solution lurking somewhere.

Edit: this "works", but the declaration files still don't use ".ts" extensions in their imports...

7. Use deno bundle with an import map

Unfortunately, deno bundle can't produce declaration files! Otherwise, this would probably be the easiest option to automate.

8. Copy the published lib and its corresponding types package from NPM

I'm hoping to remove NPM from my workflow, but this has worked for me in the recent past.

Edit: if the declarations are split across multiple files, I believe this will suffer from the same "no extensions" problem as option 6.

[David-Else]

Edit: maybe there's a Deno-focused/compatible bundler I missed?

Did you see the official esbuild deno extension? https://github.com/esbuild/deno-esbuild . It is not really mentioned in the docs, you can read a bit more evanw/esbuild#936

You have a lot of good questions, I look forward to reading the answers.

[jaredkrinke]

Did you see the official esbuild deno extension? https://github.com/esbuild/deno-esbuild . It is not really mentioned in the docs, you can read a bit more evanw/esbuild#936

I hadn't seen deno-esbuild, thanks. After looking at it for a few minutes, it looks like a wrapper around esbuild. Is that right?

It's still not obvious to me that esbuild can help with the "make a vanilla TypeScript library work in Deno" problem. The esbuild docs indicate that types are erased, so I didn't investigate further:

The declaration TypeScript configuration option (i.e. generation of .d.ts files) is not supported. If you are writing a library in TypeScript and you want to publish the compiled JavaScript code as a package for others to use, you will probably also want to publish type declarations. This is not something that esbuild can do for you because it doesn't retain any type information. You will likely either need to use the TypeScript compiler to generate them or manually write them yourself.

[jaredkrinke]

For option 5, note that import maps support scoping rules by path, so although it would be unreasonable (in my opinion) to tell consumers of a library that they need to add something to their import map, at least it wouldn't break any existing import map the consumer had.

[jaredkrinke]

One additional note: I believe TypeScript allows importing TypeScript files with .js extensions, so then you could run tsc and just consume the resulting JavaScript and declaration files in Deno. But this only works in TypeScript libraries that decided to add .js to their imports (which I've never seen in the wild, even though I personally think it makes more sense than just relying on the runtime to find the correct file).

[ayonli]

Coming from the year 2023, although Deno has supported npm: prefix now, it still doesn't support type declarations in the NPM packages, it's hard to imagine, that Deno, something strongly typed from the beginning becomes so untyped in the end.