Incorrect info about Declaration Maps

[ekwoka]

The docs say

TypeScript declaration maps are mainly used to quickly jump to type definitions in the context of a monorepo (see source issue and official documentation).

They should not be included in a published NPM package and should not be confused with sourcemaps.

But this is 100% wrong.

Without declaration maps there is no way for a consumer of the package to be able to use the go to definition in IDEs like VSCode. Without declaration maps, this will do to a d.ts file, which is already where the go to type definition goes.

Without the declaration maps, the consumer has to easy way to find the actual code that is being run when using a function from an imported library.

I'm sure all of you here have been annoyed by that once, and THIS HERE IS THE REASON. Including declaration maps means the go to definition will actually work.

I don't know if there is any way for TSUP to support this without just using TSC, but this advice here is absolutely incorrect. All libraries should include the declaration maps and TS source for our dev tools to work properly.

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[hiimjasmine00]

TypeScript declaration maps are mainly used to quickly jump to type definitions in the context of a monorepo (see [source issue](https://github.com/Microsoft/TypeScript/issues/14479) and [official documentation](https://www.typescriptlang.org/tsconfig/#declarationMap)).

They should not be included in a published NPM package and should not be confused with sourcemaps.

[Tsup is not able to generate those files](https://github.com/egoist/tsup/issues/564). Instead, you should use the TypeScript compiler directly, by running the following command after the build is done: tsc --emitDeclarationOnly --declaration.

You can combine this command with Tsup [onSuccess](https://tsup.egoist.dev/#onsuccess) callback.

[ekwoka]

Yes, that one.

The information is wrong, and really awful advice for making the TS ecosystem function properly.

[altano]

I don't know if there is any way for TSUP to support this without just using TSC, but this advice here is absolutely incorrect. All libraries should include the declaration maps and TS source for our dev tools to work properly.

@ekwoka, what's your use case as the consumer of a library? Why would you want "go to definition" to go to published ts source files?

[ekwoka]

Why does "go to definition" exist? Is that what your question is? Because that's what it's supposed to do is go to the source of the thing. "Go to type definition" goes to the type definition. "Go to definition" is supposed to go to he source. Without declaration maps it doesn't so that.

Understanding how a library works is part of understanding your tools and is extremely helpful when debugging. It's even called "source diving".

I'd be shocked if there's anyone who has been working in TypeScript for longer than 3 months that HASN'T wanted to see the source and gotten burned by this relationship being broken.

The poor source diving behavior in TypeScript (due to package publishers leaving out valuable information) is an oft pointed to issue compared to other languages.

[altano]

Oh, sorry, let me clarify: as a consumer of a library (not the author) I would expect and want "go to definition" to go to the compiled JS (and not the .d.ts file).

[segevfiner]

It would be really nice to support them whether you want to publish them or not. It will be really helpful for development in a monorepo, using tsc to generate types is not as convenient as having tsup do it builtin. tsup currently uses rollup-plugin-dts which doesn't support declaration maps, and is in maintenance mode so will never support it either. I think @rollup/plugin-typescript and/or rollup-plugin-typescript2 might support source maps but it is quite different in nature to rollup-plugin-dts and might be using tsc under the hood and actually running type checking which I think the author of tsup doesn't want for performance.

[ekwoka]

Oh, sorry, let me clarify: as a consumer of a library (not the author) I would expect and want "go to definition" to go to the compiled JS (and not the .d.ts file).

@altano

Well, it doesn't do that.

the options are to have it go to a .d.ts file because no declaration maps are present, or have it go to the source typescript, because the declaration maps are present.

That's what this is about.

Without declaration maps, it goes to d.ts files (both go to definition and go to type definition go to .d.ts files. with declaration maps, the go to definition would go to the source .ts files.

And I don't see why anyone would want it to go to the js and not the ts, but regardless, that isn't really an option here.

[ekwoka]

@segevfiner Vite has plugins that do support declaration maps, which I use for everything. I'm more bringing this issue here, because tsup is used by quite a lot, and not only doesn't support an IMPORTANT feature of typescript IDE support, but also directly conveys entirely inaccurate information about the importance of it.

[segevfiner]

Seems like rollup-plugin-dts also uses tsc/typescript under the hood. So switchig to @rollup/plugin-typescript or rollup-plugin-typescript2 will only lose us the bundling of d.ts files.

[segevfiner]

Something as simple as:

rollup.plugin.ts:

import { defineConfig } from "rollup";
import typescript from "@rollup/plugin-typescript";

export default defineConfig({
  input: "./src/index.ts",
  output: {
    dir: "./dist",
    format: "esm",
    sourcemap: true,
  },
  plugins: [typescript({ tsconfig: "./tsconfig.json" })],
});

tsconfig.json:

{
    "extends": "@tsconfig/node18/tsconfig.json",
    "include": ["src/**/*"],
    "compilerOptions": {
        "rootDir": "src",
        "outDir": "dist",
        "module": "ES2022",
        "moduleResolution": "bundler",
        "declaration": true,
        "declarationMap": true,
        "sourceMap": true
    }
}

Was able to generate d.ts with declaration maps. It is likely tsup can integrate @rollup/plugin-typescript or rollup-plugin-typescript2 instead of rollup-plugin-dts or as an option beside it to support the generation of declaration maps rather easily, which will be very useful. (Of course you still need whatever trick tsup uses to get rollup to not generate actual JS files, and probably enable emitDeclarationOnly, and we might have some trouble with composite and the outputToFilesystem flag).

@egoist Thoughts?

[tuananhlai]

I agree with the OP about the importance of declaration map files. It's quite annoying when you want to see the source code and the IDE leads you to the type declaration files.

[segevfiner]

I wonder if the new experimental api-extractor based dts generation can be made to generate declaration maps.

[ocavue]

I wonder if the new experimental api-extractor based dts generation can be made to generate declaration maps.

No, at least for now. @microsoft/api-extractor, which is used under the new --experimental-dts flag, does not support .d.ts.map files rollup. See the upstream issue: microsoft/rushstack#1886