Add monorepo support doc

Author: ryyppy

_blogposts/2020-12-07-release-8-4.mdx

@@ -55,30 +55,9 @@ dependent's command line flags for building binary artifacts. Such strategy bene
 
 ### Introducing `pinned-dependencies`
 
-To make `bsb -make-world` more practical, we also introduce a new concept called: `pinned-dependencies`.
-In general, packages are classified as three categories:
-
-- toplevel
-  - warnings reported
-  - warn-error respected
-  - build dev dependency
-  - run custom rules
-  - package-specs like ES6/CommonJS overrides all its dependencies
-- pinned dependencies
-  - warnings reported
-  - warn-error respected
-  - build dev dependency
-  - run custom rules
-- normal dependencies
-  - warnings, warn-error ignored
-  - ignore dev directories
-  - ignore custom generator rules
-
-Previously, we only had `toplevel` and `normal dependencies`, by introducing `pinned-dependencies`,
-such package will be built mostly like `toplevel` packages.
-
-The usage is quite simple, add `pinned-dependencies` in the toplevel package's `bsconfig.json`.
-Note such field only make sense in toplevel's configuration.
+To make `bsb -make-world` more practical for e.g. monorepo setups (`lerna`, `yarn workspaces`, etc.), we introduced a new concept called `pinned-dependencies`. A pinned dependency allows us to automatically rebuild packages that are pinned by a toplevel package, like your final webapp.
+
+Please refer to our [Monorepo Setup](/docs/manual/latest/build-monorepos) docs for more information on how to use `pinned-dependencies` with different monorepo setups.
 
 ### More robust handling of removal of staled output
 

data/sidebar_manual_latest.json

@@ -53,6 +53,7 @@
     "build-overview",
     "build-configuration",
     "build-configuration-schema",
+    "build-monorepos",
     "interop-with-js-build-systems",
     "build-performance"
   ],

pages/docs/manual/latest/build-monorepos.mdx

@@ -0,0 +1,107 @@
+---
+title: "Monorepo Setup"
+metaTitle: "Monorepo Setup"
+description: "Configuring ReScript in a monorepo like setup"
+canonical: "/docs/manual/latest/build-monorepos"
+---
+
+# Monorepo Setup
+
+**Since 8.4**
+
+We usually recommend using ReScript in a single-codebase style, where there is only one `bsconfig.json` file for the whole codebase. Many JavaScript libraries maintain multiple packages in one single codebase though, and use `yarn workspaces` to cross-link packages locally for development.
+
+This workflow is not straightforward for ReScript usage, so we need to explain some additional concepts to make this work. There are three different kinds of packages:
+
+- Toplevel (this is usually the final app you are building, which has dependencies to other packages)
+- Pinned dependencies (these are your local packages that should always rebuild when you build your toplevel, those should be listed in `bs-dependencies` and `pinned-dependencies`)
+- Normal dependencies (these are packages that are consumed from npm and listed via `bs-dependencies`)
+
+Whenever a package is being built (`bsb -make-world`), the build system will build the toplevel package with its pinned-dependencies. So any changes made in a pinned dependency will automatically be reflected in the final app.
+
+## Build System Package Rules
+
+The build system respects the following rules for each package type:
+
+**Toplevel**
+- Warnings reported
+- Warn-error respected
+- Builds dev dependencies
+- Builds pinned dependencies
+- Runs custom rules
+- Package-specs like ES6/CommonJS overrides all its dependencies
+
+**Pinned dependencies**
+- Warnings reported
+- Warn-error respected
+- Ignores pinned dependencies
+- Builds dev dependencies
+- Runs custom rules
+
+**Normal dependencies**
+- Warnings, warn-error ignored
+- Ignores dev directories
+- Ignores pinned dependencies
+- Ignores custom generator rules
+
+## Examples
+
+### Yarn workspaces
+
+Let's assume we have a codebase like this:
+
+```
+myproject/
+  app/
+   - src/App.res
+   - bsconfig.json
+  common/
+   - src/Header.res
+   - bsconfig.json
+  myplugin/
+   - src/MyPlugin.res
+   - bsconfig.json
+  package.json
+```
+
+Our `package.json` file within our codebase root would look like this:
+
+```json
+{
+  "name": "myproject",
+  "private": true,
+  "workspaces": {
+    "packages": [
+      "app",
+      "common",
+      "legacy"
+    ]
+  }
+}
+```
+
+
+Our `app` folder would be our toplevel package, consuming our `common` and `myplugin` packages as `pinned-dependencies`. The configuration for `app/bsconfig.json` looks like this:
+
+```json
+{
+  "name": "app",
+  "version": "1.0.0",
+  "sources": {
+    "dir" : "src",
+    "subdirs" : true
+  },
+  /* ... */
+  "bs-dependencies": [
+    "common",
+    "myplugin"
+  ],
+  "pinned-dependencies": ["common", "myplugin"],
+  /* ... */
+}
+```
+
+Now, whenever we are running `npx bsb -make-world` within our `app` package, the compiler would always rebuild any changes within its pinned dependencies as well.
+
+**Important:** ReScript will not rebuild any `pinned-dependencies` in watch mode! This is due to the complexity of file watching, so you'd need to set up your own file-watcher process that runs `bsb -make-world` on specific file changes. E.g. you could use [`watchman-make`](https://facebook.github.io/watchman/docs/watchman-make.html) to automatically run the build task when a file in `common` or `myplugin` has been changed.
+