# Monorepo Roundup

## Steps to Make Libraries Publishable
1. If you're rebuilding, update your nx version to 15.
2. Ensure that you use the publishable tag properly when generating code for the library
https://nx.dev/more-concepts/buildable-and-publishable-libraries
3. If the library is a base level dependency (meaning that it needs to generate all dependencies on install, use ``"buildableProjectDepsInPackageJsonType": "dependencies"`` in the project.json build options.

I'm thinking that highlevel dependencies that may not have new deps on their own might be able to use ``peerDependencies`` if all their dependencies were already imported in the lower level libs.

4. If we're using css in our libraries make sure to use `extractCss: false` so that the build can inject the CSS directly into the document body. Our old plugins did this automatically for us. The new ones do not.


5. For the rebuild team, it is absolutely essential that we keep things minimal. We can layer in our automation over time. Right now we need packages that ship. The root cause of our build problem still isn't 100% known (though I have some ideas). So it's important to build from the ground up and isolate things that could have been the problem as we build.

6. Test everything after every change. Keep a local app build and a external app that pulls from npm.

## Current Test Repo

The current test repo is extremely minimal.

- there's no versioning (I have to update locally when deploying to NPM).
- There's no CI.
- I ripped storybook out of UI.
- TS is a little bit stricter
- but it does allow module interop at the root level.
- There's no more apps or libs. Everything exists in one folder called packages (how NX 15 works now).
- There's no workspace.json. NX 15 doesn't generate a workspace JSON.

Everyone should also read this. It's a breakdown of packaged based repos vs. integrated repos. We're using an integrated repo.

https://nx.dev/concepts/integrated-vs-package-based

## Isolating Root Causes

Even though I was able to get things working, I was unable to pinpoint the exact cause. This makes me feel a little uneasy, and I feel that in order to be able to use our monorepo well, we should isolate this.

Here are some of the potential causes, listed in order of their likelyhood (based on my guess) of being the root cause.

However, there's a lot of excess duct-tape in the existing monorepo that deviates far from the way that nx generates a project, so there could be a lot of other potential causes.

1) A combination of 2) and 3).
2) We just weren't using the --publishable tag properly. There's no way to audit this once the code is generated, so it's really hard to discern if that's the case.
3) We weren't building out our base repos to include all dependencies in the package JSON. Some were set to peerDeps (see UI), others it wasn't specified at all. I couldn't find any reasoning for these decisions, and IMO, the dependencies seem to be layered backwards (High level libs should be peerDeps, Low level should be deps). It's worth noting that I tested this earlier, and it still didn't work with switching this config around, which makes me think that this also has something to do with the --publishable tag
4) UMD exports. The new mono compiles to regular js. I'm not sure why we're compiling to umd in the old repo, if this is was by design or some quirk of an older version.
5) Vite stuff. There's no Vite code in the new repo. This could also be the cause. It's worth noting that the both Vite and regular nrwl/react plugins both use Rollup as a bunder, so my initial thinking around rollup being a cause is unlikely.
6) Other bloat. There's a lot of custom config to get libraries that we don't need up and running. There could be some base level config that I couldn't spot that's changing things around on us.

## Plans of attack

### Just rebuild, isolate root causes as we go.

This would be an all-hands rebuild of the app. Some folks layer in old deps and test them out. Others build the CI and versioning system. We save everything that's not a TS library for last.

Then, if we still haven't identified a reproducible root cause, we send one person to find that while the rest of the team goes back to regular development.

Pros:
- **Less things to patch together.** NX is very poorly documented and if something goes wrong, you'll be digging through potentially thousands of GH issued to get it working. For example, in order for to get CSS injected in the UI lib, I had to read every issue in their monorepo (open or closed) with the words ``css`` in it. This took at least six hours of reading. Eventually, I found an old issue from years ago where someone mentioned a potential solution that didn't work for them. This fix is necessary for anyone who is making a UI lib (React or otherwise) and importing raw CSS, in other words, anyone who wants to make a publishable component library. Imagine how difficult it would be find something else.
- **NX 15.** NX is now using 15. V14 docs are gone and have fun using the wayback machine to try and read them. This can also be a con (see below)
- **We know what's going on.** Just by the nature of building from the ground up and testing each change, we can isolate which part isn't working. This allows us to properly search for solutions or fixes.
- **Better communication.** If we're all on one team, communicating regularly, there would likely be a faster momentum.
- **Better understanding** Everyone gets their hands dirty and can see how this thing comes together. Smaller silo.
- **Cleaner code/fresh start** We get to rethink a lot of our earlier decisions that we made early in our journer, when we didn't really know what we were doing. Also, we get to clean out a lot of the config that we don't need. For example, the new repo has one set of TS rules for all the libs and apps.

Cons:

- We might end up spending more time than we need.
- We might lose tooling that we didn't need to cut (ex. Maybe Vite wasn't causing the problems after all)
- We lose git history
- All or most of the NX video tutorials are using NX 14, so we lose everything there. Its worth mentioning that at least currently, 15 is close enough to 14 at the plugin level (not at the high level)
- Some of that duct tape may have been necessary.
- Travis has to migrate all GH issues

### Red Team/Blue Team. Take what we've learned and apply it to both repos.

Essentially, we split into two teams. One team builds from the ground up. The other tries to get the old mono running.

Don't think I need to breakdown pros and cons here. It's basically an inverse of the above list.

## Final thoughts:

- I'm leaning towards a new build. Lots of long term benefit there.
- I also feel that new build is the surest way of getting up and running, even though it may not be the fastest. Even doing things the slow way, as long as there's no serious edge cases, we can get our libraries reasonably fast while layering in some of our other stuff later on.