[heft] Great readme! Except.. what does it do?

[gregjacobs]

https://rushstack.io/pages/heft/overview/

Guys, it's all well and good that Heft is "Scalable, Familiar, Polished and complete, Extensible, Optimized, and Professional," but you haven't explained what it is or what it does on the intro page!

Great, "it's an extensible build system." What does it build? Is it for just web projects or any project? Is it for individual packages or monorepos? Is it supposed to replace the tsc command? Is it supposed to replace rollup/webpack? Or is it supposed to just call these things? Replace the need for npm scripts?

You mention it works with or without Rush, but what's the difference from Rush and how does it interact with it? Is it meant to do smarter rebuilds? (Is it a competitor to Nx or Bazel?)

Like, really, what is it?

:)

[octogonz]

I remember @wbern giving some similar feedback. Let's fix it.

[octogonz]

The README intro currently says:

Heft is an extensible build system designed for use with the Rush Stack family of tools. You don’t need a monorepo to use Heft, however. It also works well for small standalone projects. Compared to other similar systems, Heft has some unique design goals:

Here's a proposed revision of that text:

Heft is an extensible toolchain that invokes other popular tools such as TypeScript, ESLint, Jest, Webpack, and API Extractor. You can use it to build web applications, Node.js services, command-line tools, libraries, and more.

Heft is typically invoked as the "build" action from your project's package.json file. It's designed for use in a monorepo with potentially hundreds of other projects, where the Rush orchestrator invokes a "build" script separately in each project folder. In this situation, everything must build as fast as possible. Special purpose scripts become a headache to maintain, so it's better to replace them with a reusable engine that's driven by config files. Once that's set up, you'll want to minimize duplication of config files across projects. Lastly, you'll want to define a small set of stereotypical project types ("rigs") that you will maintain, and discourage projects from overriding the rig configuration, so that any person can easily contribute to any project. Heft is a ready-made implementation of all these ideas.

You don’t need a monorepo to use Heft, however. It also works well for small standalone projects. Compared to other similar systems, Heft has some unique design goals:

@gregjacobs Does this address all your questions? Let me know if you have more questions/additions/changes, otherwise I can make a PR to update the README.md.

[octogonz]

Is it supposed to replace rollup/webpack?

Heft has built-in support for specific tools (Webpack instead of Rolllup, Jest instead of Mocha, TypeScript but not Babel, etc). Because Heft is extensible, it's certainly possible to make plugins that would enable those other choices. But it's important to understand that the maintainers don't see flexibility of tooling as inherently advantageous. Instead, the focus is on flexibility of being able to build many different types of projects, with a very polished developer experience, which requires deep integration with each tool. (For example if we implement custom Webpack plugins, it would be expensive to maintain equivalent Rollup plugins. For TypeScript, we call a bunch of internal compiler APIs to make it build really fast. For Jest, we implemented our own equivalent of ts-jest with a very different architecture.)

I feel like this information is already communicated in the other feature bullets, but if not let me know.

[octogonz]

Here's the PR: #2562