Include a worktop build command

[lukeed]

I've been going back on forth on this for a while... Basically, it's a debate between:

1. Include a worktop CLI that builds a Worker for you
2. Offer a series of bundler plugins that you can import/attach to your existing toolkit

I suppose it's possible to do both, but the array of plugins would be second-class in that scenario, especially since it's (probably) unlikely that each integration could offer the same level of output refinement.

---

PROs

It'd be nice to have a ready-to-go build system for you, allowing (most) users to avoid the webpack that wrangler includes. This would solve low-hanging issues (eg #62, #73, #81). There's already very little reason to use webpack anyway, but really, this is the only unmatched benefit to offering a build-in CLI solution. In other words, even with a worktop/webpack plugin, there's still the "exports" and ESM resolving issue that I (as the plugin) can't fix without risking other resolutions breaking.

That said, just to reiterate, any esbuild/swc/Rollup configuration works out of the box. Webpack is purposefully counter-compliant here. 👎

Either as a worktop CLI or as a series of plugins, I'm going to want to do AST transformations. For long before worktop's first public release, I've had a PoC that compiles away the worktop Router in production. Even though the Router is already fast and lightweight, this removes all doubt and produces the most optimized form of the equivalent routing logic.

If I ship a CLI, it's easier to defend including an entire @swc/core installation. It also means that worktop could lean into other compile-time optimizations/rewrites. Going the plugins route, I'd have to sheepishly include all of @swc/core anyway, which is kinda like embedding a bundler within your existing bundler, or rewrite all the same AST operations using the target system's offerings –– i've explored this for another project... it's not fun.

CONs

• Becomes an extra config file to learn/manage (can offer good defaults, but still)
• Having a worktop build sorta implies the existence/inevitably of a worktop dev command
  Can always attach miniflare/equivalent, but the expectation will be there and creates far more scope.
• Project scope grows significantly, especially trying to accomodate all existing user config
• Worktop is actually really easy/simple to build now. It doesn't need any of the special sauce I'm talking about here.

---

Current Stance

Right now, I'm thinking that if I do this, it'd all take place under another package. That would mean that your package.json looks something like this:

{
  "scripts": {
    "build": "worktop build"
  },
  "dependencies": {
    "worktop": "latest"
  },
  "devDependencies": {
    "worktop-builder": "latest"
  }
}

This way, you only buy into all of the build-time optimizations if you decide to actually use/install worktop-builder (name tbd). If you don't install and use the toolkit, then you use worktop as you/we already do today.

Two quick polls to (anonymously) weigh in on the points raised here. Thank you~! 🙇

Plugins vs CLI

Single vs Separate Packages

[evanderkoogh]

I think there are 2 valid use-cases for a CLI. Making it even more trivial to generate a worker for simple use-cases and to use it to compile out Worktop altogether.

If I have a medium complexity worker that happens to use Worktop I already have a bundler solution setup and I don't need anything special from Worktop right? If you have a small CLI included in worktop with a worktop bundle cmd that just does all the bundling things, that would be great for the first use-case. It means I start a worktop project, throw in some routes and some logic.. call worktop bundle and just ship that.

But the compiling out of the Router object is way too interesting an experiment to not attempt. And I agree that you don't want to ship that complexity into the regular worktop component. So it makes sense to create another package worktop-compile that supports that entire flow.

[lukeed]

@evanderkoogh yea exactly. The counterpoint here that I forgot to mention is that I already have cfw which does already have easy/instant cfw build and even cfw deploy commands built in. I made it to have a ready-to-go, agnostic build tool that supports monorepos out of the box (because I never have just 1 worker per domain).

So, today, you can already create a Worker with worktop & build it with cfw without any configuration needed.

But this solution misses out on the optimizations part of the equation.

[e0]

Initially it sounds like this would be nice for the dev experience but the point about the project scope seems like it could be a lot of work for relatively little gain. I don't know much about these different build systems (webpack vs rollup vs esbuild) but I do know that I have never liked webpack.

After a quick look, it looks like esbuild and swc are really interesting alternatives. I would try to get one of these to work with my current project and see if there is a noticeable difference compared to webpack when it comes to re-building the project during development. I think for me, and maybe other developers, it would be ideal to have a starter template with worktop and esbuild/swc.

Looking back now, I guess I didn't think of exploring other options since webpack is default for wrangler. Even with webpack though, there hasn't been any real problems since the initial hiccup with #62 and I could entirely focus on developing without thinking about the framework.

I can't really comment on the other technical points since I don't understand them enough. Just wanted to provide some thoughts on the onboarding experience. If that (onboarding) is a main motivation for considering this issue I personally feel like some effort in documentation/examples would be enough.

[terkelg]

Providing plugins for those who want/need the extra optimization seems like the best solution.
I'm leaning towards keeping worktop simple and let cfw be the ready-to-go build system and have it come with a preset to do this optimization trough plugins.

[lukeed]

Closing in favor of #95, which tracks the optimization work specifically. Already merged #94 which added the worktop.build package for a fast, simple-to-use bundler.

This will serve as an easy-yet-configurable solution for building a worktop Worker (or any Worker) instead of the default webpack nightmare that ships with wrangler by default.