Improve tooling of reactist

[gnapse]

⁉️ Why

• To make it easier to make new releases with fixes and new features
• To make it easier to work with Reactist locally, in development mode, alongside our product apps
• To bring Reactist build process closer to how our apps are built, and support the same bundling features

🗺 Overview

• Releasing new Reactist versions is cumbersome (requires manual update of changelog, manual update of new version number, generating built artifacts, etc.)
• Working with Reactist locally against our product apps is difficult and error-prone. Although not stated below explicitly in any given task, hopefully an improved build process could help in this regard. For instance, right now stylesheet changes in Reactist do not reflect in our apps running locally against the local dev version of Reactist.
• Reactist build process and bundling features are not 100% compatible with that of our apps. We want to support the same features (e.g. importing SVGs as React components, support the same types of stylesheet imports into JS code, etc.)

✅ Task Breakdown

1. Build Process

   We want to unify and simplify our build process while making it faster if possible. This includes:

   • Remove built artifacts from source control (Do we need built assets in git #252)
   • Switch off from TSDX to another setup (webpack? esbuild? Something else?)
     • Should we make storybook and our apps build share the same build process (related: Storybook should consume bundles being created by tsdx/rollup #465)
   • Support tree-shaking. Apps and other libraries using Reactist must only include strictly what they are using from it, and nothing more.
   • Support TypeScript, CSS modules and SVGs imported as React components. It must also support .less while we still rely on it, as we gradually move away from it.

2. Automated project life-cycle

   Implement automation of versioning and release. This could be achieved drawing inspiration, for instance, from how jest-dom does it (powered internally by cycjimmy/semantic-release-action).

   This includes:

   • Having actions that make sure that all commits and/or PR titles follow the Angular Commit Message Conventions.
   • The release automation draws conclusions from the commits/PRs in the release, to determine if the release is a patch, minor or major (breaking change) release.
   • Push actions to main trigger a new release fully automatically, including determining the new version.
   • Automated release of storybooks to https://doist.github.io/reactist/

3. PR review process aids

   • Add a live storybook to every PR. Inspired by Doist/frontend-toolbox#56.

🚧 Potential problems / unknowns

• We may not be able to fit all this work within a single cycle (4-5 weeks).

  The numbered list above is in order of priority. Hopefully all the checkboxes within each section are done, and no numbered section is left halfway, as they are more or less self-contained and all tasks within each are interconnected.

🔮 Out of scope / future improvements

• Package vs. per-module imports
• Support/use vanilla-extract (see all the build systems with which vanilla-extract can be integrated).
• Post to a thread in Twist (not sure if we want that for an open source project. It could be something we achieve externally via some sort of Github-Twist integration).
• Set up all-contributors. Most notably or specifically, set up the all-contributors bot so that we can semi-automate this task.
• Set up Cypress Component Testing (this will most probably be part of @gnapse's Personal DO before the end of 2022).

📝 Related documents & discussion

• Wishlist for Reactist tooling/setup improvements

[frankieyan]

A proposal from @pawelgrimm (ref) is to switch away from publishing Reactist as an npm package, and leveraging shadcn's cli - which lives in https://github.com/shadcn/ui - allowing the Reactist source files to be copied into consumer codebases in an automated. way. This avoids having to rely on the "link" mechanism when dealing with local npm packages and docker.

Pros/cons:

• 👍 Much easier to customize
• 👍 No real build process needed in Reactist (shadcn already provides the script to “compile” the registry)
• 👍 Better DX (develop directly against todoist-web, then commit the same patch to Reactist)
• 👎 Worse upgrade experience (manually integrate updates from Reactist into todoist-web)
• 👎 Looser constraints (i.e. Reactist can’t impose any hard rules, they can be overridden easily within the consuming code)

To make this work, we'll have to enforce (whether automated or not) on the todoist-web side that Reactist source files are not to be manipulated, similar to how we treat other build artifacts like colour variables.

Next step: small PoC to demonstrate to the team how this works.

[gnapse]

Thanks for summarizing that down, @frankieyan. It's really helpful.

About those cons.

Worse upgrade experience (manually integrate updates from Reactist into todoist-web)

Why is this exactly worse? Assuming we have a script to do it, it should not be too different from increasing a version number in package.json and running npm install. Or am I missing something?

Looser constraints (i.e. Reactist can’t impose any hard rules, they can be overridden easily within the consuming code)

I could see that as a positive, depending on how easily things can be overridden. As in "can they be inadvertently overridden easily?" or is it more like "they can be easily overridden, but doing it is explicit enough so that you are unlike to do it by accident".

By "overriding" you refer to what you talk about at the end, regarding the modification of the Reactist artifacts? If so, then I agree that we should do something to prevent that, and possibly we can do that. Or is the "overriding con" about other types of overrides?