When is tsc not enough?

[tyleralbee]

Summary

I love the new additions to the docs. That said, it feels that there may be places where the best practices in the docs are misaligned with the state of the examples in the repo.

For example, the docs state in the Best Practices section for TypeScript:

For Internal Packages, we recommend that you use tsc to compile your TypeScript libraries whenever possible. While you can use a bundler, it's not necessary and adds extra complexity to your build process. Additionally, bundling a library can mangle the code before it makes it to your applications' bundlers, causing hard to debug issues.

However, in the examples/, we can see tsup being used often in internal packages, such as the kitchen-sink logger.

Some internal packages, such as the kitchen-sink ui package, have a clear reason for doing so:

import { defineConfig, type Options } from "tsup";

export default defineConfig((options: Options) => ({
  entry: ["./src/index.tsx"],
  format: ["cjs", "esm"],
  dts: true,
  external: ["react"],
  banner: {
    js: "'use client'",
  },
  ...options,
}));

I actually don't know if that is flat out impossible with tsc, but from what I understand, Microsoft is generally against tsc augmenting the emitted .js at build time. Correct me if I'm wrong: I am figuring that this is a situation in which we'd want to use a bundler like tsup.

Can someone explain why that would be the case for the logger?

import { defineConfig, type Options } from "tsup";

export default defineConfig((options: Options) => ({
  entryPoints: ["src/index.ts"],
  clean: true,
  dts: true,
  format: ["cjs"],
  ...options,
}));

Is it just that the examples are lagging behind the philosophy or am I missing something?

Additional information

• The example I am referencing: kitchen-sink
• Turborepo docs: TypeScript Best Practices

Example

No response

[wujekbogdan]

The short answer is: use a bundler when you need ... bundling :)

A bundler does a bunch of things, such as:

• Bundling itself - it creates one *.js output file, while tsc emits as many *.js files as the number of *.ts files it compiles.
• Tree shaking
• You can import other file formats, such as *.graphql or *.css, with custom loaders.
• It can apply polyfills, such as the __dirname shim for ESM.
• It can apply precise environment targeting, e.g., with browserlists, while tsc only compiles to a predefined target (e.g., ES2022).

[anthonyshew]

This is generally the reasoning. I'll also add that the examples currently are not updated. I'm going to be working on that shortly.

[hwangyena]

Hello, @wujekbogdan
Thank you for your explanation! After reading the documentation, I have a follow-up question I’d like to ask.

In the Turbo documentation, it states here:

The majority of Compiled Packages should use tsc. Since the package is highly likely to be consumed by an application that is using a bundler, the application's bundler will prepare the library package for distribution in the application's final bundles, handling polyfilling, downleveling, and other concerns. A bundler should only be used if you have a specific use case that requires it, like bundling static assets into your package's outputs.

Based on this, I understand that when another application package consumes the internal package, there is no need to worry about polyfilling, downleveling, or other concerns (doesn’t this include browserlists as well?).

• It can apply polyfills, such as the __dirname shim for ESM.
• It can apply precise environment targeting, e.g., with browserlists, while tsc only compiles to a predefined target (e.g., ES2022).

So, does this mean internal packages used by the application package don't need to consider the above points?