Cleanup package scripts

We currently leverage the scripts entry in our package.json. As of right now this includes around 34 scripts that aren’t really documented. Any addition, change etc. has to be followed by contributors to be understood.

It would be nice if we could consolidate those into a single place that also adds documentation. This should put emphasis on common tasks as well as guiding contributors: What script can I use to perform X task?

https://github.com/kentcdodds/nps looks very close to what I have in mind (task + description + watch mode in a single place).

Maybe there are other solutions for large monorepos. In any case it would be nice if we could improve the first contributor experience.

[eps1lon]

Can we instead just add a new section in our documentation & document what each script does along with all it’s relevant information?

It’s part of the issue, yes. The problem is that documentation becomes easily outdated. Even putting it right next to the script won’t prevent it. A separate file (or gh wikis) would be even worse.

Since I want to enhance the scripts anyway (+debug, +watch) it’s a good opportunity to explore solutions that solve both issues (docs and better scripts).

[eps1lon]

@cvanem This issue is totally up for grabs. This is what the “help wanted” issue is for.

The important part is that I don’t want the create churn for maintainers. The old workflows shouldn’t change. It’s mainly directed at new contributors so that they don’t feel overwhelmed when looking at the package.json and can have a single entry point.

Some points ordered by importance. They are up for debate starting with point 3 and can be implemented in separate PRs:

1. document scripts
2. improve readability and “workflow splitting” Essentially extract all && piping into separate scripts. For example when debugging docs generation I don’t want to clutter my git diff by deleting all API docs.
3. Watchmode all the things!
4. Get rid of babel-node babel-node is for developing node scripts that are published. Since we only use those for internal usage we can require the latest active LTS node version. The only feature we loose is es modules and we don’t need those for local dev. It also creates overhead when running the scripts because they have to be transpiled first.
5. Document how to run the scripts with a debugger attached This is where no babel-node will help because we don’t have to fight source maps.

nps isn’t a requirement for this. From skimming the readme it just seemed like this would address 1 and 2.