Preserve comments?

[MatthewSH]

I'm packaging my library up but I'm using JS/TSdoc to handle documentation. The issue is that pkgroll strips these comments away.

It's enough of an issue that I might have to look at TSUp and wondering if you have any solutions for it.

[privatenumber]

Are you running with minification enabled?

[MatthewSH]

No I am not (unless there's something else happening by default). You can see the output on this package if you like: https://www.npmjs.com/package/rivalsjs?activeTab=code

Code: https://github.com/MatthewSH/rivalsjs

In all fairness I should've double checked before publishing to ensure it was preserving them.

I tried to use as slim as possible.

Should also note that this is my first time actively using pkgroll in a project over TSUp so I may have configured it incorrectly.

[privatenumber]

I see, thanks for the code—helps a lot.

The TypeScript syntax is compiled by esbuild which doesn't preserve comments.

However in your case, you can emit .d.ts files which should preserve the TSdocs.

[MatthewSH]

I'm on mobile at the moment so excuse my ignorance but are you referring to a CLI flag to output or a configuration setting?

Also is there any way we can modify the underlying config or have an option to preserve comments? Even if it's just referencing the TSConfig compiler option (which I also tested but didn't work)

[privatenumber]

Nope, you just set the .d.ts files in the exports like from the example in the README.

In this example, it uses .d.cts and .d.mts to explicitly indicate whether its a CommonJS module or ES module:

    "exports": {
        "require": {
            "types": "./dist/index.d.cts",
            "default": "./dist/index.cjs",
        },
        "import": {
            "types": "./dist/index.d.mts",
            "default": "./dist/index.mjs",
        },
    },

Learn more on this here:
https://hirok.io/posts/package-json-exports#targeting-node-js-esm-cjs-type-definitions

---

esbuild just doesn't support preserving comments in the parsing stage and only made exceptions for special kind of comments like legal or important ones (/*!).

[MatthewSH]

That puts me in a weird position because I have subpaths and have typings per subpath.

[MatthewSH]

For further context, the library is intended to by used like (slimmed a bit from the readme):

import { createRivalsClient } from 'rivalsjs'
import { getHealthCheck } from 'rivalsjs/v1'

const client = createRivalsClient({
  apiKey: 'your-api-key'
})

const healthcheck = await getHealthCheck(client)

If this is outside the scope of pkgroll, that's completely okay and I'm fine with using TSUp! It's about using the right tool for the right job. Just feels a bit strange that JSDoc comments are stripped of all comments.

[privatenumber]

That's a perfectly normal use-case. But your setup is incorrect.
See the TS docs here: https://www.typescriptlang.org/docs/handbook/modules/reference.html#example-explicit-types-condition

I'll try to update my blog post to be clearer.

[privatenumber]

JSYK tsup uses esbuild so you have the same limitation.

The common practice isn't preserving JSDocs but emitting d.ts files.