RFC - Create a monorepo for NGXS Labs

[markwhitfeld]

NGXS Labs Monorepo RFC

Background

NGXS labs has been a great place for plugin development, but we have seen issues where many authors are not familiar with publishing packages and don't keep dependencies up to date as needed. Sometimes the authors contribute and then disappear. We would like to create a monorepo to support most of the fundamentals of managing a plugin without the headache of maintenance.

Proposal

(Proposed by @markwhitfeld )

To create a monorepo for the plugins with the following requirements:

• NX seems like a very good option for the overall workspace
  • buildable & publishable libs
  • cloud cache
  • good tooling support & plugins
  • schematics
  • apparently the npm preset is the best one to use for our needs
  • strict types should be enabled by default for libs
• Primary branch should be called main and not master
• Lib author/team rights management
  • leverage github CODEOWNERS
  • auto-assign issues/PRs
  • auto-label issues/PRs too?
  • author has rights to merge to main branch within plugin area
  • proposed folder structure:
  • packages/firestore-plugin:
    • lib: contains the library
    • integration: contains the integration apps and/or tests
    • docs?: we could publish per plugin docs too or just use markdown
• Dependency management
  • shared dependency management for most libs
  • option for independent dependency management as needed for specific libs
  • for example, for integration apps, or for libs that need more work to align
  • yarn or lerna offers the ability to have independent versioning for specific folders
  • dependabot or equivalent for automatic dependency update PRs
• CI / CD pipelines set up
  • github actions seems to be the obvious choice
  • should report progress clearly
  • should provide ability to pinpoint an issue easily
  • each plugin is run separately using the github actions build matrix:
  • https://docs.github.com/en/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
  • https://ncorti.com/blog/howto-github-actions-build-matrix
• Formatting
  • most likely prettier
  • enable es5 trailing comma format
  • to run as part of pre-commit hook
  • to run as part of PR checks
• Linting
  • eslint
  • to run as part of PR checks
• Commit format
  • semantic commits
  • check to run as part of pre-commit hook
  • to run as part of PR checks
• Versioning
  • semantic versioning by default
  • plugins independently versioned
  • nx plugin available: https://github.com/jscutlery/semver
  • conventional changelog: https://github.com/conventional-changelog/standard-version
• Publishing
  • auto-publishing from main by default only when libs change
  • lerna apparently does this well, but not sure what other approaches there are
  • lib could opt to rather do a GitHub action approval step before publish
  • even configure the specifics of permissions for this: https://cloudlumberjack.com/posts/github-actions-approvals/
  • could have environments set up for each of the plugins eg. firestore-plugin-prod etc
• Issue templates (just like NGXS)
• PR management
  • bundle change reporting
  • coverage change reporting
• Bundle size management
  • basic requirements here: https://github.com/ngxs/store/issues/1764
  • bundlemon looks good
• Reports
  • code coverage
  • bundle size history? (not sure if anything does this)
  • sonar-cube or equivalent
  • suggestions in comments please?
• Integration app testing
  • this looks great for backwards-compatibility testing:
  • https://github.com/ngworker/angular-versions-action
  • @LayZeeDK mentioned that he would help us with any questions with this
• Import existing repos
  • It would be great to import existing repos with commit history
  • Could use npx lerna import --preserve-commit .... to do this (unless there is a better tool?)

Nice to have

• Publish docs for each plugin
  • could be shared docs site
  • could just be markdown in the repo
• Could leverage other CI offerings to run the CI as well as a double check (CircleCI/Azure Devops/etc)

Reference examples

• Had some good advice on this tweet: https://twitter.com/MarkWhitfeld/status/1440223532777021448
• The NX repo uses NX to manage multiple libs:
  • https://github.com/nrwl/nx
• The ngWorker repo is probably set up very well
  • @LayZeeDK recommended that it is worth a look. Really love his work.
  • https://github.com/ngworker/ngworker
• @brandonroberts made this repo example for us
  • It demonstrates the use of yarn or lerna to have some libs with independent dependency versioning
  • https://github.com/brandonroberts/ngxs-labs-nx
• @brandonroberts also recommended that we look at the ngrx repo too
• Please recommend any others that you have seen in the comments

[LayZeeDK]

Notion to use main instead of master.