Generate type declarations during bun build

[kynnyhsap]

What is the problem this feature would solve?

I'd like to build my library written in typescript with bun build (both for dev and prod), but there's no point in doing so if I or my library's users won't have type declarations. I am developing this library in the ecosystem of other projects, so often it looks like npm run dev:my-library && npm run dev:my-frontend. This is a common pattern for developing in monorepos. My current solution is tsc, which is slow in watch mode and has its drawbacks.

What is the feature you are proposing to solve the problem?

--type-declarations flag for build command to generate types along with js files.

What alternatives have you considered?

I see no workaround.

[colinhacks]

This is out of scope for Bun. Currently tsc is the only tool in existence for reliably generating declaration files. Doing it right would require re-implementing the entire TypeScript compiler & type inference infrastructure unfortunately.

This may be possible in some limited cases eventually.

[The-Code-Monkey]

@colinhacks I would have to disagree with you, the whole point of bun which is pointed out it to be a compiler, typescript, test runner and more. If you haven't implemented one of the main features of typescript which is types, how can you expect people to build a typescript library with it, as there will never be any type definitions.

And also Im pretty sure on https://bun.sh/blog/bun-v1.0 it litterally states that it is a replacement for tsc apart from typechecking, typechecking is fine but the actual usage of compiled types for development is a massive dealbreaker for me and probably will be for others.

Due to the reasons most people would want to move away from tsc is because speed but your just telling us to use it anyway.

Edit: because of this inability to generate types using bun, bun therefore isnt a drop in replacement for node and tsc, and actually breaks the functionality of libs.

[tomquirk]

It seems like given this stance, library authors who want to provide types can't really use bun build for their libs/packages (every author except DHH) 🤷 .

Not a dealbreaker (can still use other parts of bun), but worth noting.

[Jarred-Sumner]

My expectation is that Isolated Declarations will eventually ship in TypeScript and then some number of weeks or months later, we will ship support for emitting TypeScript types in bun build(for projects leveraging isolated declarations)

[The-Code-Monkey]

👍 Thanks for clarification @Jarred-Sumner will this be something that bun will automatically do, if it notices the repo is using typescript

[paperdave]

When isolated declarations is stabilized, I think Bun should support that. It'll let us generate the d.ts files quickly, in exchange for some requirements on the source code (have to annotate each exported fn with a return type)

For now, a third-party tool i use on my own projects is https://github.com/timocov/dts-bundle-generator.
Someone from the community even made a plugin for it: https://github.com/wobsoriano/bun-plugin-dts

To me, that's more of a workaround than a real solution (it's quite slow), but it works for now.

[joaopaulomoraes]

As a workaround, you can generate the type declaration with just tsc in an additional command in your package.json.

Eg:

"scripts": {
  "build": "bun build ... && bun run build:declaration",
  "build:declaration": "tsc --emitDeclarationOnly --project tsconfig.types.json"
}

So you have the build followed by the generation of declarations that can be added to the build command or executed separately.

[danielfalk]

As a workaround, you can generate the type declaration with just tsc in an additional command in your package.json.

Eg:

"scripts": {
  "build": "bun build ... && bun run build:declaration",
  "build:declaration": "tsc --emitDeclarationOnly --project tsconfig.types.json"
}

So you have the build followed by the generation of declarations that can be added to the build command or executed separately.

Is there any advantage to doing this as opposed to just using tsc for building? It seems like it would be slower to have two different process for building that have to run in sequence.

[JacobWeisenburger]

https://github.com/wobsoriano/bun-plugin-dts

[ryoppippi]

https://github.com/ryoppippi/bun-plugin-isolated-decl

[RobinTail]

Could bun operate tsc internally and build a declaration file of the bundle like tsup does?

https://tsup.egoist.dev/#generate-declaration-file

tsup	bun
export default defineConfig({ entry: ["src/index.ts"], format: ["esm", "cjs"], splitting: false, sourcemap: false, minify: true, clean: true, dts: true, platform: "browser", });	await Bun.build({ entrypoints: ["src/index.ts"], format: "esm", // CJS — missing splitting: false, sourcemap: "none", minify: true, outdir: "dist", // dts — missing target: "browser", });

@JacobWeisenburger
https://github.com/wobsoriano/bun-plugin-dts

That plugin does not work at all:

[local] ➜  merge-sx git:(try-bun) ✗ bun build.ts
354 | }
355 | exports.getRootSourceFile = getRootSourceFile;
356 | function getNodeOwnSymbol(node, typeChecker) {
357 |     const nodeSymbol = typeChecker.getSymbolAtLocation(node);
358 |     if (nodeSymbol === undefined) {
359 |         throw new Error(`Cannot find symbol for node "${node.getText()}" in "${node.parent.getText()}" from "${node.getSourceFile().fileName}"`);
                    ^
error: Cannot find symbol for node "window" in "window.matchMedia"

@ryoppippi
https://github.com/ryoppippi/bun-plugin-isolated-decl

That one does work, with minor issue (fixed).
And it's also worth it to note that it wipes JSDoc out at the moment.

[jftanner]

My expectation is that Isolated Declarations will eventually ship in TypeScript and then some number of weeks or months later, we will ship support for emitting TypeScript types in bun build(for projects leveraging isolated declarations)

It looks like that feature has been cancelled. Hopefully there's an updated plan for Bun?

It seems to me like the current intended audience for Bun is end-user app developers. If you're writing a server, service, task, etc, then it's amazing. But it's not currently particularly viable for library developers, since it can't emit types to be used down-stream and there's no built-in publish command.

So far, I see three options, each with a distinct disadvantage:

• Add a tsc --emitDeclarationOnly to the build script. This is probably fine, but the whole reason to use Bun in a library is to avoid configuring and running tsc.
• Use a community plugin like bun-plugin-dts or bun-plugin-isolated-decl. With absolutely no disrespect intended to the plugin authors, they're just too new and under-used to be trusted for anything sensitive yet. At <1200 and <200 downloads per week respectively, the "many eyes on" trust that open-source relies on just hasn't been built yet. Especially for something that directly modifies output code at publish time. The risk of supply-chain attacks is just too high.
• Use NPM and TSC for library development and Bun only for end products. This misses out on a lot of benefits of Bun. It also introduces some risk and fragility for multi-component apps, since the dependency components will be tested in a different runtime.

My ideal solution for building libraries would be two-fold: an enhancement to bun build to automatically builds types (however it can, even if that means running tsc under the covers), and an bun publish command to replace NPM entirely. (The latter is in at least more than one other issue, so doesn't need to be discussed here.)

[paperdave]

It looks like that feature has been cancelled.

No, it was re-designed from the Pr we linked earlier, and is shipped in TypeScript 5.5.

https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#isolated-declarations

been keeping my eyes on this and the doors are open for us to start working on us since typescript has defined how they will work. i just currently have a bunch of other priorities before this one.

for now tsc --emitDeclarationOnly --isolatedDeclarations is the best choice. i kind of recommend having typescript configured to some degree regardless, as it is important to perform type checking (something only tsc can do). i recommend --isolatedDeclarations so that when bun build does types, it will be a drop-in replacement.

[jftanner]

No, it was re-designed from the Pr we linked earlier, and is shipped in TypeScript 5.5.
Oh, fantastic!

This is all very good news. Thank you for the update.
And thank you all, as well, for the project as a whole. It's a monumental undertaking, and what you've delivered already is very impressive.

[RobinTail]

for now tsc --emitDeclarationOnly --isolatedDeclarations is the best choice.

can it bundle declarations by an entrypoint (make a single DTS file from many TS, similar to JS bundle), @paperdave ?

[huseeiin]

When isolated declarations is stabilized, I think Bun should support that. It'll let us generate the d.ts files quickly, in exchange for some requirements on the source code (have to annotate each exported fn with a return type)

For now, a third-party tool i use on my own projects is https://github.com/timocov/dts-bundle-generator. Someone from the community even made a plugin for it: https://github.com/wobsoriano/bun-plugin-dts

To me, that's more of a workaround than a real solution (it's quite slow), but it works for now.

oxc supports that without having to add explicit return types on functions: https://github.com/unplugin/unplugin-isolated-decl though it removes comments sadly: