isolate-package 1.3.3 → 1.4.1-0

package/README.md

@@ -1,21 +1,24 @@
 # Isolate Package
 
-Isolate a monorepo workspace package so that it can be deployed as a completely
-self-contained directory with the sources of all its local dependencies
-included.
+Isolate a monorepo workspace package to form a self-contained deployable package
+that includes internal dependencies and a compatible lockfile.
 
 <!-- TOC -->
 
-- [Motivation](#motivation)
 - [Features](#features)
-- [Firebase Deployment Quickstart](#firebase-deployment-quickstart)
+- [Motivation](#motivation)
+- [Install](#install)
+- [Usage as binary](#usage-as-binary)
+- [Usage as function](#usage-as-function)
 - [Prerequisites](#prerequisites)
-  - [Define shared package dependencies in the manifest](#define-shared-package-dependencies-in-the-manifest)
-  - [Define "files" and "version" in each manifest](#define-files-and-version-in-each-manifest)
+  - [Define shared dependencies in the package manifest](#define-shared-dependencies-in-the-package-manifest)
+  - [Define "version" field in each package manifest](#define-version-field-in-each-package-manifest)
+  - [Define "files" field in each package manifest](#define-files-field-in-each-package-manifest)
   - [Use a flat structure inside your packages folders](#use-a-flat-structure-inside-your-packages-folders)
-- [Usage](#usage)
-  - [Deploying to Firebase](#deploying-to-firebase)
-  - [Deploying to Firebase from the root](#deploying-to-firebase-from-the-root)
+- [Working with Firebase](#working-with-firebase)
+  - [A Quick Start](#a-quick-start)
+  - [Deploying from multiple packages](#deploying-from-multiple-packages)
+  - [Deploying from the root](#deploying-from-the-root)
 - [Configuration Options](#configuration-options)
   - [buildDirName](#builddirname)
   - [excludeLockfile](#excludelockfile)
@@ -28,77 +31,96 @@ included.
   - [workspaceRoot](#workspaceroot)
 - [Troubleshooting](#troubleshooting)
 - [Lockfiles](#lockfiles)
+  - [PNPM](#pnpm)
   - [NPM](#npm)
-  - [PNPM Lockfiles disabled for now](#pnpm-lockfiles-disabled-for-now)
+  - [Yarn](#yarn)
+  - [A Partial Workaround](#a-partial-workaround)
 - [Different Package Managers](#different-package-managers)
-  - [Yarn v1 and v3](#yarn-v1-and-v3)
 - [Using the Firebase Functions Emulator](#using-the-firebase-functions-emulator)
+- [The internal packages strategy](#the-internal-packages-strategy)
 
 <!-- /TOC -->
 
+## Features
+
+- Isolate a monorepo package with its internal dependencies to form a
+  self-contained installable package.
+- Deterministic deployment by generating an isolated lockfile based on the
+  existing monorepo lockfile. Currently this feature is only supported for PNPM.
+  See [lockfiles](#lockfiles) for more information.
+- Zero-config for the vast majority of use-cases, with no manual steps involved.
+- Support for PNPM, NPM and Yarn.
+- Compatible with the Firebase tools CLI, incl 1st gen and 2nd gen Firebase
+  functions deployments.
+- Uses a pack/unpack approach to isolate only those files that would have been
+  part of a published NPM package.
+- Isolates internal workspace dependencies recursively. If package A depends on
+  internal package B which depends on internal package C, all of them will be
+  included.
+- Optionally include devDependencies in the isolated output.
+
 ## Motivation
 
-This solution was developed out of a desire to deploy to
-[Firebase](https://firebase.google.com/) from a monorepo without resorting to
-hacks, shell scripts and manual tasks. I have written an article explaining the
-issue [here](https://medium.com/p/e685de39025e).
+This solution was born from a desire to deploy to
+[Firebase](https://firebase.google.com/) from a monorepo without requiring
+custom shell scripts and other hacks. Here is
+[an article](https://thijs-koerselman.medium.com/deploy-to-firebase-without-the-hacks-e685de39025e)
+explaining the issue in more detail.
 
-There is nothing Firebase specific to this solution but I am currently not aware
-of other reasons to isolate a workspace package. If you find a different
-use-case, I would love to hear about it.
+There is nothing Firebase-specific to this solution and there should be other
+use-cases for it, but that is why this documentation contains some instructions
+related to Firebase.
 
-In the documentation and code you will see the word "manifest" a lot, and it
-simply means to the contents of a `package.json` file.
+## Install
 
-## Features
+Run `pnpm install isolate-package --dev` or the equivalent for `yarn` or `npm`.
 
-- Zero-config for the vast majority of use-cases, with no manual steps involved.
-- Support NPM, Yarn classic (v1) and current (v3) and PNPM.
-- Fully compatible with the Firebase tools CLI, supporting 1st gen and 2nd gen
-  Firebase functions.
-- Uses a pack/unpack approach to isolate only the files that would have been
-  part of a published package, so the output contains a minimal set of files.
-- Isolates shared dependencies recursively. If package A depends on local
-  package B which depends on local package C, all of them will be isolated.
-- Includes the lockfile so the isolated deployment should be deterministic. PNPM
-  lockfiles are not supported yet. See [lockfiles](#lockfiles) for more info.
-- Optionally include devDependencies in the isolated output.
+I recommend using `pnpm` for
+[a number of reasons](https://pnpm.io/feature-comparison). Also, at the time of
+writing it is the only package manager for which isolate-package can generate a
+lockfile. For more information see [lockfiles](#lockfiles).
 
-## Firebase Deployment Quickstart
+## Usage as binary
 
-This describes the steps required for Firebase deployment, assuming:
+This package exposes a binary called `isolate`.
 
-- You use a fairly typical monorepo setup
-- Your `firebase.json` config lives in the root of the package that you like to
-  deploy to Firebase, hereafter referred to as the "target package".
+Run `npx isolate` from the root of the package you want to isolate. Make sure
+you build the package first.
 
-If you use a different setup, just continue reading the
-[Prerequisites](#prerequisites) section.
+The `isolate` binary will try to infer your build output location from a
+`tsconfig` file, but see the [buildDirName configuration](#builddirname) if you
+are not using Typescript.
 
-1. In the target package, install isolate-package and firebase-tools by running
-   `pnpm add isolate-package firebase-tools -D` or the Yarn / NPM equivalent. I
-   like to install firebase-tools as a devDependency in every firebase package,
-   but you could of course also use a global install if you prefer.
-2. In the `firebase.json` config set `"source"` to `"./isolate"` and
-   `"predeploy"` to `["turbo build", "isolate"]` or whatever suits your build
-   tool.
-3. From the target package root, you should now be able to deploy with `npx
-firebase deploy` or `npx firebase deploy --only functions` in case your package
-   only contains code for Firebase functions.
+By default the isolated output will become available at `./isolate`.
 
-I recommend keeping a `firebase.json` file inside each Firebase package (as
-opposed to the monorepo root), because it allows you to deploy from multiple
-independent packages. This give you more flexibility to organize your code. It
-also makes it easy to deploy 1st gen functions next to 2nd gen functions, or mix
-different node versions should you want to. Your bundle sizes and dependency
-lists for each function might also decrease, which improves cold-start times.
+If you are here to simplify and improve your Firebase deployments check out the
+[Firebase quick start guide](#a-quick-start).
+
+## Usage as function
+
+Alternatively, `isolate` can be integrated in other programs by importing it as
+a function. You optionally pass it a some user configuration and possibly a
+logger to handle any output messages should you need to write them to a
+different location as the standard `node:console`.
+
+```ts
+import { isolate } from "isolate-package";
+
+await isolate({
+  config: { logLevel: "debug" },
+  logger: customLogger,
+});
+```
+
+If you do not pass in any configuration, the function will try to read a
+`isolate.config.json` file from disk. You can set
 
 ## Prerequisites
 
 Because historically many different approaches to monorepos exist, we need to
 establish some basic rules for the isolate process to work.
 
-### Define shared package dependencies in the manifest
+### Define shared dependencies in the package manifest
 
 This one might sound obvious, but if the `package.json` from the package you are
 targeting does not list the other monorepo packages it depends on, in either the
@@ -124,14 +146,23 @@ work (some depending on your package manager):
 So if the a package name can be found as part of the workspace definition, it
 will be processed regardless of its version specifier.
 
-### Define "files" and "version" in each manifest
+### Define "version" field in each package manifest
+
+The `version` field is required for `pack` to execute, because it is use to
+generate part of the packed filename. A personal preference is to set it to
+`"0.0.0"` to indicate that the version does not have any real meaning.
+
+### Define "files" field in each package manifest
+
+> NOTE: This step is not required if you use the
+> [internal packages strategy](#the-internal-packages-strategy)
 
 The isolate process uses (p)npm `pack` to extract files from package
 directories, just like publishing a package would.
 
 For this to work it is required that you define the `files` property in each
-`package.json` manifest, as it declares what files should be included in the
-published output.
+package manifest, as it declares what files should be included in the published
+output.
 
 Typically the value contains an array with just the name of the build output
 directory, for example:
@@ -143,15 +174,11 @@ directory, for example:
 }
 ```
 
-The `version` field is also required for `pack` to execute. I personally always
-set it to `"0.0.0"` to indicate that the version does not have a practical
-function.
-
 A few additional files will be included by `pack` automatically, like the
 `package.json` and `README.md` files.
 
-**Tip** If you deploy to Firebase [2nd
-generation](https://firebase.google.com/docs/firestore/extend-with-functions-2nd-gen)
+**Tip** If you deploy to Firebase
+[2nd generation](https://firebase.google.com/docs/firestore/extend-with-functions-2nd-gen)
 functions, you might want to include some .env files in the "files" list, so
 they are packaged and deployed together with your build output (as 1st gen
 functions config is no longer supported).
@@ -160,32 +187,58 @@ functions config is no longer supported).
 
 At the moment, nesting packages inside packages is not supported.
 
-When building the registry of all local packages, `isolate` doesn't drill down
-into the folders. So if you declare your packages to live in `packages/*` it
-will only find the packages directly in that folder and not at
+When building the registry of all internal packages, `isolate` doesn't drill
+down into the folders. So if you declare your packages to live in `packages/*`
+it will only find the packages directly in that folder and not at
 `packages/nested/more-packages`.
 
-You can, however, declare multiple packages folders. I personally like to use
-`["packages/*", "apps/*", "services/*"]`. It's just that the structure inside
-them should be flat.
+You can, however, declare multiple workspace packages directories. Personally, I
+prefer to use `["packages/*", "apps/*", "services/*"]`. It is only the structure
+inside them that should be flat.
 
-## Usage
+## Working with Firebase
 
-Run `npm install isolate-package --dev` or the equivalent for `yarn` or `pnpm`.
+### A Quick Start
 
-This package exposes the `isolate` executable. Once installed you can run `npx
-isolate` in any package directory _after_ you have build the source files. By
-default this will produce a directory at `./isolate` but this can be configured.
+If you are not confident that your monorepo setup is solid, please check out my
+in-dept example at [mono-ts](https://github.com/0x80/mono-ts) where many
+different aspects are discussed and `isolate-package` is used to demonstrate
+Firebase deployments.
 
-You will probably want to add the output directory to your `.gitignore` file.
+This section describes the steps required for Firebase deployment, assuming:
 
-### Deploying to Firebase
+- You use a fairly typical monorepo setup
+- Your `firebase.json` config lives in the root of the package that you like to
+  deploy to Firebase, hereafter referred to as the "target package".
+
+If your setup diverges from a traditional one, please continue reading the
+[Prerequisites](#prerequisites) section.
 
-You can deploy to Firebase from multiple packages in your monorepo, so I advise
-you to co-locate your `firebase.json` file with the source code, and not place
-it in the root of the monorepo. If you do want to keep the firebase config in
-the root, read the instructions for [deploying to Firebase from the
-root](#deploying-to-firebase-from-the-root).
+1. In the target package, install `isolate-package` and `firebase-tools` by
+   running `pnpm add isolate-package firebase-tools -D` or the Yarn / NPM
+   equivalent. I tend to install firebase-tools as a devDependency in every
+   Firebase package, but you could also use a global install if you prefer that.
+2. In the `firebase.json` config set `"source"` to `"./isolate"` and
+   `"predeploy"` to `["turbo build", "isolate"]` or whatever suits your build
+   tool. The important part here is that isolate is being executed after the
+   build stage.
+3. From the target package folder, you should now be able to deploy with
+   `npx firebase deploy`.
+
+I recommend keeping a `firebase.json` file inside each Firebase package (as
+opposed to the monorepo root), because it allows you to deploy from multiple
+independent packages. It makes it easy to deploy 1st gen functions next to 2nd
+gen functions, deploy different node versions, and decrease the built output
+size and dependency lists for each package, improving deployment and cold-start
+times.
+
+### Deploying from multiple packages
+
+You can deploy to Firebase from multiple packages in your monorepo, in which
+case you co-locate your `firebase.json` file with the source code, and not in
+the root of the monorepo. If you do want to keep the firebase config in the
+root, read the instructions for
+[deploying to Firebase from the root](#deploying-to-firebase-from-the-root).
 
 In order to deploy to Firebase, the `functions.source` setting in
 `firebase.json` needs to point to the isolated output folder, which would be
@@ -210,15 +263,15 @@ from the package.
 
 If you like to deploy to Firebase Functions from multiple packages you will also
 need to configure a unique `codebase` identifier for each of them. For more
-information, [read
-this](https://firebase.google.com/docs/functions/beta/organize-functions).
+information,
+[read this](https://firebase.google.com/docs/functions/beta/organize-functions).
 
 Make sure your Firebase package adheres to the things mentioned in
-[prerequisites](#prerequisites) and its manifest file contains the field
+[prerequisites](#prerequisites) and its package manifest contains the field
 `"main"`, or `"module"` if you set `"type": "module"`, so Firebase knows the
 entry point to your source code.
 
-### Deploying to Firebase from the root
+### Deploying from the root
 
 If, for some reason, you choose to keep the `firebase.json` file in the root of
 the monorepo you will have to place a configuration file called
@@ -248,8 +301,8 @@ The Firebase configuration should then look something like this:
 For most users no configuration should be necessary.
 
 You can configure the isolate process by placing a `isolate.config.json` file in
-the package that you want to isolate, except when you're [deploying to Firebase
-from the root of the workspace](#deploying-firebase-from-the-root).
+the package that you want to isolate, except when you're
+[deploying to Firebase from the root of the workspace](#deploying-firebase-from-the-root).
 
 For the config file to be picked up, you will have to execute `isolate` from the
 same location, as it uses the current working directory.
@@ -268,15 +321,14 @@ setting to specify where the build output files are located.
 
 Type: `boolean`, default: Depends on package manager.
 
-Sets the inclusion or exclusion of the lockfile as part of the deployment. For
-Yarn and NPM the lockfiles are included by default, but for PNPM they are
-excluded by default because they are not supported yet. For more information see
-[lockfiles](#lockfiles).
+Sets the inclusion or exclusion of the lockfile as part of the deployment.
+
+PNPM lockfiles are regenerated based on the isolated output, so they are
+included by default.
 
-_Tip:_ If you can't use a lockfile I advise you to declare dependencies using
-absolute versions in your manifest files. This doesn't prevent their
-dependencies from installing newer versions, but at least you minimize the risk
-of things breaking.
+For NPM and Yarn the lockfiles are excluded by default because they are
+currently copied as-is to the isolate output and can lead to issues during
+deployment installs. For more information see [lockfiles](#lockfiles).
 
 ### includeDevDependencies
 
@@ -298,7 +350,7 @@ Type: `"info" | "debug" | "warn" | "error"`, default: `"info"`.
 
 Because the configuration loader depends on this setting, its output is not
 affected by this setting. If you want to debug the configuration set
-`ISOLATE_CONFIG_LOG_LEVEL=debug` before you run `isolate`
+`DEBUG_ISOLATE_CONFIG=true` before you run `isolate`
 
 ### targetPackagePath
 
@@ -344,84 +396,108 @@ want to isolate is located 2 levels up from the root.
 For example
 
 ```
+packages
+├─ backend
+│  └─ package.json
+└─ ui
+   └─ package.json
 apps
-├─ api
-│  ├─ package.json
-│  └─ .eslintrc.js
+├─ admin
+│  └─ package.json
 └─ web
-   ├─ package.json
-   └─ .eslintrc.js
-packages
-└─ eslint-config-custom
-   ├─ index.js
    └─ package.json
+services
+└─ api
+   └─ package.json
+
 ```
 
 When you use the `targetPackagePath` option, this setting will be ignored.
 
 ## Troubleshooting
 
-If something is not working, I advise you to add a `isolate.config.json` file,
-and set `"logLevel"` to `"debug"`. This should give you detailed feedback in the
+If something is not working as expected, add a `isolate.config.json` file, and
+set `"logLevel"` to `"debug"`. This should give you detailed feedback in the
 console.
 
 In addition define an environment variable to debug the configuration being used
-by setting `ISOLATE_CONFIG_LOG_LEVEL=debug` before you execute `isolate`
+by setting `DEBUG_ISOLATE_CONFIG=true` before you execute `isolate`.
 
 When debugging Firebase deployment issues it might be convenient to trigger the
 isolate process manually with `npx isolate` and possibly
-`ISOLATE_CONFIG_LOG_LEVEL=debug npx isolate`
+`DEBUG_ISOLATE_CONFIG=true npx isolate`
 
 ## Lockfiles
 
-The lockfiles for NPM as well as the Yarn v1 and v3 seem to have a flat
-structure unrelated to the workspace packages structure, so they are copied to
-the isolate output as-is.
+Deploying the isolated code together with a valid lockfile turned out to be the
+biggest challenge of this solution.
+
+A lockfile in a monorepo describes the dependencies of all packages, and does
+not necessarily translate to the isolated output without altering it. Different
+package managers use very different formats, and it might not be enough to do a
+find/replace on some paths.
+
+It is also not possibly to generate a brand new lockfile from the isolated code
+by mimicking a fresh install, because versions would be able to diverge and thus
+it would negate the whole point of having a lockfile in the first place.
 
-The PNPM lockfile clearly has a structure describing the different packages by
-their relative paths, and so to correct the lockfile it is adapted before being
-stored to the isolate directory.
+What we need is to re-generate a lockfile for the isolated output based on the
+versions that are currently installed and locked in the monorepo lockfile.
+
+### PNPM
+
+For PNPM a new isolated lockfile is generated.
 
 ### NPM
 
-It seems that when using NPM the `npm ci` can fail with a message like:
+For now, NPM lockfiles are simply copied over to the isolated output. I have
+seen Firebase deployments work with it, but likely you are going to run into an
+error like this:
 
 > `npm ci` can only install packages when your package.json and
 > package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock
 > file with `npm install` before continuing.
 
-I haven't been able to figure out what causes this. I have seen NPM deploys
-working with lockfiles, but I can not reliably reproduce it.
+If you experience this issue, you can choose to exclude the lockfile from
+deployment by setting `"excludeLockfile": false` in your isolate.config.json
+file, or make the move to PNPM (recommended).
+
+A real solution, regenerating an isolated lockfile, should be possible based on
+the
+[NPM CLI Arborist](https://github.com/npm/cli/tree/latest/workspaces/arborist)
+code, so I plan to look into that in the near future.
 
-If you experience this issue I have two suggestions:
+### Yarn
 
-- Upgrade to Node 18 by setting the `"runtime": "nodejs18"` in your
-  firebase.json config. Note that you most likely also have to re-create your
-  lockfile using Node 18.
-- Exclude the lockfile from deployment by setting `"excludeLockfile": false` in
-  your isolate.config.json file.
+For now, Yarn lockfiles are simply copied over to the isolated output. I believe
+I have seen Firebase deployments work with it, but it is likely you will run
+into an error.
 
-I hope we can eventually figure out what is causing this, but more investigation
-is required.
+If you experience an issue, you can choose to exclude the lockfile from
+deployment by setting `"excludeLockfile": false` in your isolate.config.json
+file, or make the move to PNPM (recommended).
 
-### PNPM Lockfiles disabled for now
+I am not aware of any code in the official Yarn repository for re-generating a
+lockfile, and I am reluctant to work on this feature based on user-land code.
 
-There is still [an issue with the PNPM lockfile
-conversion](https://github.com/0x80/isolate-package/issues/5) which makes it
-unusable at the moment. Until that is resolved, the lockfile is automatically
-excluded for PNPM.
+Personally, I do not think Yarn is very relevant anymore in 2023 and I recommend
+switching to PNPM.
 
-_Tip:_ If you can't use a lockfile I advise you to declare dependencies using
-absolute versions in your manifest files. This doesn't prevent their
-dependencies from installing newer versions, but at least you minimize the risk
-of things breaking.
+### A Partial Workaround
+
+If you can not use a lockfile, because you depend on NPM or Yarn, a partial
+workaround would be to declare dependencies using exact versions in your package
+manifest. This doesn't prevent your dependencies-dependencies from installing
+newer versions, like a lockfile would, but at least you minimize the risk of
+things breaking.
 
 ## Different Package Managers
 
-Isolate package has been designed to work with all package managers. It has been
-testing it with NPM 8, 9, Yarn 1.22, Yarn 3.6 and PNPM 8.
+Isolate package has been designed to work with all package managers, although
+[PNPM is recommended](https://pnpm.io/feature-comparison), especially for
+monorepo environments.
 
-The isolate process will infer the package manager name and version from the
+The isolation process will infer the package manager name and version from the
 type of lockfile found and the version that the OS reports for the installed
 executable. This information is then used to change some of its behavior. For
 example, the PNPM `pack` process is preferred over the default NPM `pack` if
@@ -430,41 +506,62 @@ PNPM in used, simply because it seems to be much faster.
 The Firebase cloud deploy pipeline will use the package manager that matches
 lockfile that was found in the deployed package.
 
-### Yarn v1 and v3
-
-If you are using Yarn 3 with zero-installs, the deployed package is not aware of
-that, because the `.yarnrc` file and `.yarn` folder are located in the root of
-your monorepo, and the version is not recorded as part of the lockfile. Therefor
-the Firebase deploy cloud pipeline will use Yarn 1 to install your dependencies.
-I don't think that is an issue but it might be good to know.
-
 ## Using the Firebase Functions Emulator
 
 The Firebase functions emulator runs on the code that firebase.json `source`
-points to. Unfortunately, this is the same location as is used for uploading the
-code for deployment, which means the emulator is forced to use the isolated
-output.
+points to. Unfortunately, this is the same field as is used for declaring the
+code for deployment, which means the emulator is looking at the isolated output.
 
-As a result, any changes to your code first need to go through the isolate
-process in order to be picked up by the emulator. In other words, changes do not
-propagate automatically while the emulator is running.
+As a result, any changes to your code have to go through the isolate process in
+order to be picked up by the emulator. In other words, changes do not propagate
+automatically while the emulator is running.
 
-The strategy I use at the moment is to create a "emulate" script in your
-manifest which does the same as the Firebase predeploy, and then starts the
-emulator. For example:
+The workaround I use at the moment is to create a "emulate" script in the
+package manifest which does the same as the Firebase predeploy, and then starts
+the emulator. For example:
 
 `turbo build && isolate && firebase emulators:start --only functions`
 
-But you will still have to stop and restart the emulator on every code change,
-which is a bummer.
-
-The real solution to this, I think, involves changing the firebase-tools CLI. I
-see two options:
-
-1. Give the firebase config an extra field to distinguish between code that is
-   used by the emulator and code that is bundled for deployment.
-2. Integrate the isolate process into the firebase-tools deploy command, so it
-   is only used as part of the deployment and the `source` property can still
-   point to the original code.
-
-I plan to take this up in the near future.
+You will still have to stop and restart the emulator on every code change, which
+is unfortunate of course.
+
+A real solution to this would be to integrate isolate-package into the
+firebase-tools `deploy` command, so it is only executed as part of the
+deployment process and the `source` property can still point to the original
+code.
+
+I plan to work on this once isolate-package is bit more mature.
+
+## The internal packages strategy
+
+Recently I changed [my example monorepo setup](https://github.com/0x80/mono-ts)
+to include
+[the internal packages strategy](https://turbo.build/blog/you-might-not-need-typescript-project-references),
+(in which the package manifest entries point directly to TS source files, to
+omit the build step), and I was pleased to discover that the approach is
+compatible with `isolate-packages` with only a single change in configuration.
+
+In summary this is how it works:
+
+1. The package to be deployed lists its internal dependencies as usual, but the
+   package manifests of those dependencies point directly to the Typescript
+   source (and types).
+2. You configure the bundler of your target package to include the source code
+   for those internal packages in its output bundle. In the case of TSUP for the
+   [API service in the mono-ts](https://github.com/0x80/mono-ts/blob/main/services/api/tsup.config.ts)
+   that configuration is: `noExternal: ["@mono/common"]`
+3. When `isolate` runs, it does the exact same thing as always. It will detect
+   the internal packages, copies them to the isolate output folder and adjusts
+   any links.
+4. When deploying to Firebase, the cloud pipeline will treat the package
+   manifest as usual, which installs the listed dependencies and any
+   dependencies listed in the linked internal package manifests.
+
+Steps 3 and 4 are no different from a traditional setup.
+
+Note that the manifests for the internal packages will still point to the
+Typescript source files, but since the shared code was embedded in the deployed
+bundle, they will never be referenced via import statements and as a result the
+entry points remain unused. The only reason the packages are included in the
+isolated output is so that the package manager knows what dependencies to
+install.