Only publish dist directory to NPM

[futurGH]

Another bundle size reduction PR (: this saves ~1/3 of bundle size in the case of @atproto/api by not publishing src and tests as part of the package. PR doesn't include bsync, bsky, dev-infra, lex-cli, ozone, and pds because I figured those wouldn't really have 3rd party dependents.

(you could save another 1/3 or so of the resultant bundle size by not generating sourcemaps but that's a bit more of a tradeoff)

[devinivy]

A couple thoughts here:

• I believe we also ship sourcemaps. Without the original source do those sourcemaps become useless?
• This will reduce package size on npm, but the overall bundle size (i.e. impact within a built project, as a tool like bundlephobia would measure) will probably not change, since the original source is not included in bundles.

@matthieusieben any thoughts on this?

[futurGH]

• I believe we also ship sourcemaps. Without the original source do those sourcemaps become useless?

Sourcemaps can still help with providing source-accurate line numbers in errors to my knowledge, though I guess that'd depend on environment?

• This will reduce package size on npm, but the overall bundle size (i.e. impact within a built project, as a tool like bundlephobia would measure) will probably not change, since the original source is not included in bundles.

Point taken, though the majority of these packages seem to be meant to run in node, where you usually wouldn't be bundling dependencies.

I think the bigger issue with this setup is that TS will attempt to transpile any .ts files it finds imported under the root project's tsconfig, so if a dependent project has a tsconfig with e.g. different module settings than @atproto/api, it fails to compile due to the source being included.

[matthieusieben]

On sourcemaps

For sourcemaps to be really useful, the debugging tool (chrome debugger, Sentry, bundler, etc.) needs to have a way to reconstruct the source code. We could use TypeScript's inlineSources option instead of bundling the src directory but that would cause the npm package's size to be roughly identical as the source code would be shipped through the *.map files.

As a maintainer of the @atproto/* libs, sourcemaps are extremely valuable as they allow me to properly navigate between packages while working on them.

However, when it comes to the published version of the packages, I don't think that sourcemaps are actually that important. In my opinion, a stack trace in the built files is good enough for debugging purposes for users of our packages. When I personally debug other maintainers' packages in my node_modules, I always find it easier when there is a simple plain JS file (along with a d.ts).

Here is how some other popular tools address this:

• typeorm issues .map files that reference an ./src that is not included ("broken maps")
• @nestjs/core does not issue maps at all
• zod does not issue maps at all
• @redis/client does not issue maps at all
• vue: does not issue maps at all
• angular: map are inlined, with source code, in the js files
• rxjs: bundles src and map files pointing to them

TL;DR: I would be open to removing the src dir from the published packages as long as the way it is done:

1. does not expose broken source maps (//# sourceMappingURL=filename.js.map to non existing .map file, .map files without inlined source code and referencing missing src/ dir, etc.)
2. still allows source files to be built while maintaining the lib

[matthieusieben]

On bundling

While the practice of bundling is less frequent in back-end code, it is actually a good thing to do. node_modules contain lots of file that are not necessary in prod and actually make code execution slower (e.g. module resolution based on package.json fields, cjs vs. .mjs, etc.).

That being said, I don't believe that the published version of our packages should contain any unnecessary file. I have no clue how many people find the src dir of our published packages to be useful...

[futurGH]

Another note on this — when source files are included in node_modules, TS will attempt to type check them with no way to disable that behaviour. As a result, unless the dependent project's module/import-related tsconfig settings are identical to those of the library, there'll be transpilation errors as it attempts to transpile the atproto dependency under the parent project's tsconfig settings.

[matthieusieben]

Another note on this — when source files are included in node_modules, TS will attempt to type check them with no way to disable that behaviour. As a result, unless the dependent project's module/import-related tsconfig settings are identical to those of the library, there'll be transpilation errors as it attempts to transpile the atproto dependency under the parent project's tsconfig settings.

That shouldn't be the case though, as the package.json of our packages have their "main" and "types" fields referencing files from within ./dist/.

If you encounter errors due to the declaration files, you might want to check TS's skipLibCheck) option.

[futurGH]

skipLibCheck only disables type checking for declaration files — it has no impact on included source files