Sell me on tsup, please.

[hitsthings]

I have a TypeScript build that uses esbuild directly at the moment. I was looking for a page that describes what tsup does on top of esbuild, but haven't found it.

Can someone sell me on tsup? Should I switch my build to use it? Why should I use tsup instead of esbuild directly?

Please don't take this as questioning the usefulness of tsup - I'm sure it's got pros and cons like everything else and is useful in many situations. I am earnestly curious what tsup has to offer and am ignorant about it. I'd like to know when I should use it.

Thanks for any help!

[hitsthings]

I guess one cool thing I've found is the __dirname shim in ESM. That's pretty handy to have around!

[estruyf]

@hitsthings was looking for the same, but in my case, I was setting up something new and deciding which path I should go.

The advantage of tsup is the config options, but don't think this can be all?

[talkohavy]

The Short Answer

The output is cleaner.
Maybe there are other aspects, but this is something I noticed, which definitely won me over.

The Long Version

So I used tsup before trying out esbuild, to bundle a small package I own & maintain (eslint-plugin-ezlint).
My package works as expected (bundled with tsup) and all was well.
After learning that it's powered by esbuild I was like "Hey, why not use esbuild directly?".
I made a quick refactor (again... small project), built it with esbuild, published it, and for some reason the projects which used it stopped working. This forced me to go look inside the generated output.

- 1. What I Needed To Bundle

The most simple task ever:
I needed to bundle a js object, which was written in ES6, and have it exported as deafult. That's it!
What could possibly go wrong?

- 2. The difference in output between esbuild & tsup

Here is the output from tsup:

'use strict';

var r = {
  'array-bracket-spacing': ['error', 'never'],
  // more keys here...
};
var e = { 'sort-exports/sort-exports': ['error', { sortDir: 'asc' }] };
var s = {
  'import/no-duplicates': 'error',
  // more keys here...
};
var t = {
  'jsdoc/check-access': 'warn',
  // more keys here...
};
var o = {
  '@typescript-eslint/no-explicit-any': 'off',
  // more keys here...
};
var g = {
  configs: {
    recommended: {
      extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
      env: { node: !0, browser: !0, jest: !0, es6: !0 },
      // more keys here...
      rules: { ...r, ...s, ...e, ...t, ...o, 'no-constant-condition': 'off' },
    },
  },
};

module.exports = g;

Failrly simple, right?
Now here is the output from esbuild:

var o = Object.defineProperty;
var u = Object.getOwnPropertyDescriptor;
var d = Object.getOwnPropertyNames;
var m = Object.prototype.hasOwnProperty;
var w = (e, r) => {
    for (var t in r) o(e, t, { get: r[t], enumerable: !0 });
  },
  g = (e, r, t, a) => {
    if ((r && typeof r == 'object') || typeof r == 'function')
      for (const s of d(r))
        !m.call(e, s) && s !== t && o(e, s, { get: () => r[s], enumerable: !(a = u(r, s)) || a.enumerable });
    return e;
  };
var y = (e) => g(o({}, '__esModule', { value: !0 }), e);
var j = {};
w(j, { default: () => f });
module.exports = y(j);
var n = {
  'array-bracket-spacing': ['error', 'never'],
  // more keys here...
};
var i = { 'sort-exports/sort-exports': ['error', { sortDir: 'asc' }] };
var c = {
  'import/no-duplicates': 'error',
  // more keys here...
};
var p = {
  'jsdoc/check-access': 'warn',
  // more keys here...
};
var l = {
  '@typescript-eslint/no-explicit-any': 'off',
  // more keys here...
};
var f = {
  configs: {
    recommended: {
      extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
      env: { node: !0, browser: !0, jest: !0, es6: !0 },
      // more keys here...
      rules: { ...n, ...c, ...i, ...p, ...l, 'no-constant-condition': 'off' },
    },
  },
};

- 3. Conclusions

The output from tsup was much simpler and easy to reason about, while the output from esbuild added some uneccesary overhead and un-needed complexity - like, the task was just to export a javascript object! Why did it need to add all these moving parts? Like there's Object.defineProperty, and Object.getOwnPropertyDescriptor, and Object.getOwnPropertyNames, and Object.prototype.hasOwnProperty, and creating all these functions in between.... so unnecessary!
The result from tsup was so much cleaner.
In all fairness? I know that esbuild is probably capable of achieving the same output, but even if there is... why isn't it the default behaviour? Like why tsup behaves in such a clean way by default, where-as esbuild felt the necessity of adding these extra parts?
Anyway, this is merely my humble opinion take it with a grain of salt, and even if I one day find out how to acheive the same with esbuild, i'd probably stick to tsup just because i admire them for choosing such nice defaults in the first place. But feel free to judge on your own.
In the next part i'll present you with the configs I set in both tools, just to emphasize the simplicity of it, and also for being 100% transparent with you guys.

- 4. What the configs were

The tsup config file was:

import { defineConfig } from 'tsup';

const tsupConfig = defineConfig((_options) => ({
  entry: ['src/index.js'],
  outDir: 'dist',
  bundle: true,
  minify: true,
  format: ['cjs'],
  clean: true,
  treeshake: true,
}));

export default tsupConfig;

The esbuild config was:

import esbuild from 'esbuild';

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/index.cjs',
  minify: true,
  treeShaking: true,
  format: 'cjs',
});

[trajano]

I came from the react-native-builder bob stuff and switched to this one because it was just simpler to deal with (until I started creating Jest snapshots).

My working config was pretty simple

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src', '!src/__tests__/**', '!src/**/*.test.*'],
  sourcemap: 'inline',
  loader: {
    '.snap': 'js',
  },
});

Though there could be better ways of doing it.

My ideal was a lot simpler than others though since I just need to make it work in a monorepo https://github.com/trajano/expo-experiments in other words I don't actually have to publish any packages just need to make sure there's a folder with javascript transpiled (defaults to dist

[trajano]

One minus thing to point out, some Meta code which uses Flow or have JSX in JS files can get into issues (I just hit it just now)
For the JS vs JSX

  loader: {
    '.js': 'jsx',
  },

Will fix it

But the flow stuff, I had to do a patch-package to strip out the errant file of flow code.