Is it recommended to publish source files for TypeScript node modules?

Question

I noticed some TypeScript node modules (e.g loopback-next/packages) publish their source files with the node module. Is there a particular reason for this or is it just unnecessarily increasing the size of the module?

Musa

They only publish the .d.ts files with the .js files in the npm package, not the .ts source files. – Orthogenic

@Orthogenic they are publishing the .ts files as well, it is defined in the package.json file. For example here. This can be verified by installing the module or by running npm pack in the directory to see what will be published. – Musa

You are right. Grabbed the loopback-next package where they are not included. For @loopback/authentication you indeed find a src folder with .ts files. – Orthogenic

Answer 1

To start with a credible source: TypeScript Publishing guide only considers bundling of declaration files with the compiled .js files, no inclusion of .ts files.

Being no contributor, I could imagine two reasons for package @loopback/authentication:

1. Source Maps and debugging support (most likely)
2. usage as some kind of source package ¹

1. Source Maps and debugging support

The package authors might include source maps for debugging support, which reference/map to original .ts files in src. That way, those original sources need to be also distributed. E.g. authentication.component.js.map:

"sources": ["../src/authentication.component.ts"],

_{Side note: The sourcemap "spec" would also provide a sourcesContent field to support self contained source maps.}

2. Source package

As an alternative to precompiled files, the package offers to be not opinionated concerning the build target. So a client app project can make use of its bundler and transpile the library in a specific target format itself. For example, if you support a) Electron and b) a wide variety of browsers, you don't need extra polyfills and transformations for the Electron renderer build.

---

¹ RFC: Source Packages #4092 ; see also 2, 3 (React biased)

Orthogenic

Thanks for your answer. I was also considering the first scenario you mentioned and indeed if you include the src files + mappings while debugging it uses the .ts files instead of the .js files. I didnt even consider the second scenario you mentioned but that also makes sense, I am still unsure if it is worth to include the src files because it is a lot more code others have to download and the advantage is most of the time not that relevant. – Musa

Glad it helped. Yeah, I would consider the second scenario rather unusual for a public library. You would have source packages more in internal projects, I just mentioned it here for completeness. That scenario got present for me, when I had the task to transpile an external npm package. So include yes or no, the answer would probably be: it depends :). I prefer to treat packages as external. If I suspect an error within a package, I would clone it from github and test it isolated from the rest. – Orthogenic

I'm not sure how much that page has changed since this answer was published, but that page only refers to publishing declaration files. It doesn't really provide guidance for publishing libraries in general, so I wouldn't call it the "TypeScript Publishing Guide". – Queensland