[Discussion] Monorepo requirements for ui-router packages

[mokipedia]

As ui-router team (@christopherthielen) has expressed interest in a monorepo setup for ui-router libraries and examples, this ticket tries to define the architecture, technical requirements and non-requirements of this task.

Requirements

Repos to combine into a monorepo

• library repos
  • ui-router/core (?)
  • ui-router/react (?)
  • ui-router/angular
  • ui-router/angular-hybrid
  • ui-router/angularjs
• sample repos
  • ui-router/sample-app-react (?)
  • ui-router/sample-app-angular
  • ui-router/sample-app-angular-hybrid
  • ui-router/sample-app-angularjs
• addons (optional)
  • ui-router/rx
  • ui-router/redux (?)
  • ui-router/sticky-states (?)
  • ..?
• docs (optional)
  • ui-router/ui-router.github.io (?)

CodeQuality requirements

• prettier
• pretty-quick & husky pre-commit hooks
• eslint (tslint is deprecated)

Workspace setup

there are multiple possibilities to setup a monorepo workspace. 2 options stick out:

• lerna + separated package.json files for individual dependencies per project / lib (preferred)
• nx workspace for combined and uniform dependencies for all projects / libs

Versioning

for angular, moving forward would be easiest to drop the support for "2 last versions" in favour of synchronising with angular releases - less maintenance overhead & faster releases. for core, react and addons the current release schedule can be kept as-is

CI/Test suites

• test all affected projects on each PR
• properly run "downstream tests"

Releases

• maybe ReleasePlease?
• Automated docgen

further reference

• https://github.com/ui-router/angular/issues/951#issuecomment-983444522
• https://github.com/ui-router/angular/issues/934#issuecomment-880357840
• Current update process for angular packages: https://github.com/ui-router/angular/blob/master/add_support_for_new_angular_version.txt

[mokipedia]

i marked all repos i am unsure if it is a good idea to add them to a monorepo with ? input welcome.

also, as angular projects use it quite often, i am in favor of nx workspace over lerna, also it unifies the dependencies and simplifies the architecture a bit. however, unified dependencies can get in your way, depending on the project structure.

[christopherthielen]

Thank you, this is a good summary to start from.

1) All the repos should be moved to the monorepo 2) I have experience with lerna, but have only experimented with nx workspaces a little bit. Can you explain what is meant by unified dependencies w.r.t. nx?

I'll also add a couple of things that need consideration:

• CI/Test suites
  • test all affected projects on each PR
  • properly run "downstream tests"
• Releases (IMO ReleasePlease is a pretty good option)
  • Automated docgen

[mokipedia]

hi @christopherthielen,

ad 2) basically, nx uses one main package.json where all dependencies live in - so angular version would be the same for all projects, react version would be the same for all projects, ... or, to quote nx docs: https://nx.dev/l/a/core-concepts/why-monorepos

Single set of dependencies - Use a single version of all third-party dependencies, reducing inconsistencies between applications. Less actively developed applications are still kept up-to-date with the latest version of a framework, library, or build tool.

lerna on the other hand can (& mostly does) use own dependecies per project or lib, so splitting the definitions of dependencies in multiple package.json files inside their respective project folders

[christopherthielen]

one main package.json where all dependencies live in

Ah, I see. That doesn't seem desirable for ui-router project since it targets very different frameworks with different toolchains.

[mokipedia]

true, the toolchain is maybe a bit of a headache here. I will mark the lerna solution as preferred

[dereekb]

There was a section on NX concerning using Nx along with Lerna:

https://nx.dev/l/a/guides/lerna-and-nx

Looks like you can have separate package.json for different projects.

I've been looking at using Nx for consolidating a lot of my own cross-project code into a single repo. Haven't use either Nx or Lerna it yet so can't comment past the above link. I plan on using it soon and hopefully can come back around and help here.

[dereekb]

After using NX for a couple weeks I'm pretty happy with how it works. In terms of dependency usage, what it does is have all dependencies imported into the root package.json, but when you build the sub-libraries they have a package.json generated based off of the dependencies that are imported.

Nx's core project/workspace plugins handle building the project, but you can easily add additional commands to the workspace (I.E. a deploy function that can run build, then run a deploy function as nx deploy router-core) and reference other tooling. You'll just execute most of it from the root instead of the package's own directory.

Here's my project overview that I've been working on as an Nx workspace.

I'm unfamiliar with the build steps/pipelines that ui-router might have set up, but I don't see Nx being a blocker itself. The key is though to create each of the subprojects using the proper flags (--buildable, --publishable). I made that mistake the first time around and had to re-setup the package, but it wasn't too painful.

[dereekb]

I opened up that project at https://github.com/dereekb/dbcomponents if you want to poke around with how Nx works with a non-trivial project.

I'd be open to setting up all the projects within Nx and getting them to a base level. Just need to know which repo you'd want me to fork off of so we can merge back later, or I can just pick/start one. I figure the publishing urls probably aren't going to change (I.E. @uirouter/angular, etc.)

No timeframe for that though.

[christopherthielen]

https://github.com/christopherthielen/ui-router-monorepo-test

I've made some progress on this using yarn workspaces and lerna. I created three top level scripts:

• yarn clean
• yarn build (or yarn build --stream)
• yarn test (or yarn test --stream)

This is definitely a WIP and will likely be deleted and re-created from scratch a few times while testing things.

Some observations:

• had to nohoist a bunch of libraries to avoid conflicts
• Angular CLI keeps rewriting the package.json of @uirouter/core which is super duper annoying.
• need to figure out why some projects aren't working/testing correctly
• downstream tests aren't wired up, only unit tests.
  • some downstream tests should be removed (especially the sample apps) because their existence in the monorepo should test them with any new changes to the router(s)
  • likely going to create a directory off the root /integration_tests with the local downstream tests for projects that have them, i.e. /integration_tests/angular/typescript9.1

I'm gonna walk away from this for now, but I'll have more notes later.

[christopherthielen]

This is the series of commands I used to initialize the monorepo:

#!/usr/bin/env bash

git config --global user.email "github@sandgnat.com"
git config --global user.name "Chris Thielen"

mkdir ui-router
cd ui-router
git init
git branch -m main
yarn init -y
echo "node_modules" >> .gitignore
git add . && git commit -m "chore: initial commit"
npx --package=@spinnaker/scripts -- read-write-json write package.json "workspaces[0]" "packages/*"
npx --package=@spinnaker/scripts -- read-write-json write package.json private true
sed -i '' 's/"true"/true/' package.json
git add . && git commit -m "chore: initialize workspaces"
npx lerna init --independent
npx --package=@spinnaker/scripts -- read-write-json write lerna.json npmClient yarn
git add . && git commit -m "chore: initialize lerna"
# yarn
git add . && git commit -m "chore: initialize yarn.lock"

REPOS="publish-scripts core angularjs angular angular-hybrid react react-hybrid dsr rx redux sticky-states visualizer sample-app-angular sample-app-angular-hybrid sample-app-angularjs sample-app-react"
# REPOS="rx"
for i in $REPOS; do
  npx lerna import --flatten --preserve-commit ../$i -y;
done

rm -rf packages/yarn.lock;
yarn;
git add . && git commit -m "chore: initialize yarn.lock"

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

This does not mean that the issue is invalid. Valid issues may be reopened.

Thank you for your contributions.