JoshuaKGoldberg / JoshuaKGoldberg/create-typescript-app

🚀 Feature: Rethinking building: entry points, bundle: false, and tsup issues

Open
#1,910 2 comments 1 reaction 0 assignees View on GitHub
status: in discussion type: feature
Dominant language
TypeScript
Stars
1.4k
Forks
89
Avg merge
1m
Merged PRs (30d)
3

Description

### Bug Report Checklist

- [x] I have pulled the latest `main` branch of the repository.
- [x] I have [searched for related issues](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue) and found none that matched my issue.

### Overview

Coming over and recapping from https://github.com/JoshuaKGoldberg/eslint-fix-utils/issues/7 -> https://github.com/JoshuaKGoldberg/eslint-fix-utils/pull/13: CTA right now uses [tsup](https://tsup.egoist.dev) for production builds. tsup is a pretty darn good wrapper around [esbuild](https://esbuild.github.io). It was originally added to CTA in #623 -> #640 to avoid transpiling test files such as `*.test.*`.

tsup is configured at the moment with a couple opinionated settings:

* `bundle: false`: I prefer having output `lib/` files match the structure in `src/` for a few reasons:
* Development: faster incremental rebuilds, especially in larger packages
* Production: IMO it's easier to debug `node_modules/` contents when the structure matches
* `entry: ["src/**/*.ts", "!src/**/*.test.*"]`: since there isn't bundling, the full list of files to build needs to be told to tsup
* I think this is a bug in tsup: https://github.com/egoist/tsup/issues/1000
* Unfortunate byproduct: files that are only used in tests, like `data.fakes.ts`, still get pushed...

We've also started to see some issues with tsup falling out of maintenance a bit (💔 - sustained open source maintenance is _hard_ and _taxing_!):
* https://github.com/egoist/tsup/issues/1000
* https://github.com/egoist/tsup/issues/920
* [egoist/tsup/issues with comment count 0](https://github.com/egoist/tsup/issues?q=is%3Aissue%20state%3Aopen%20comments%3A0): 126 at time of filing

I think there are two root issues here:
* tsup is build on a _bundler_, esbuild, and is tailored to the _bundling_ use case. The file-by-file _transpilation_ use case is not as emphasized.
* tsup is not being maintained at a level needed to match its growing userbase.

Therefore, I think it would make sense to think critically about how CTA packages build `lib/` output. Is there a tool that can satisfy all the desired needs?
* File-by-file transpilation
* Tree-shaking based on entry points, not hardcoded heuristics like `*.test.*`
* Quick JS output (read: not waiting on type checking to output JS files)
* Full `.d.ts` output (read: not being limited to just what's supported in [`isolatedDeclarations`](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations))

If not, I shudder to think I might have to build one. 😬

### Additional Info

The fact that tsup exists & works at all is _awesome_. I don't mean to file this issue judgementally. https://xkcd.com/2347, https://nolanlawson.com/2017/03/05/what-it-feels-like-to-be-an-open-source-maintainer etc. etc. This is a pragmatic issue: tsup isn't completely able to do what CTA needs right now and so we need to evaluate what's best for the project.

Edit: see also https://bsky.app/profile/joshuakgoldberg.com/post/3lhgppvnyjc2e for links to other projects

🎁

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the current tsup configuration and the package build entry points described in the issue. Compare available approaches against the requested needs: file-by-file transpilation, entry-point-based tree-shaking, quick JavaScript output, and complete declaration output. Done means identifying and evaluating a build approach that satisfies those requirements for CTA packages.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
build-system, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.