isolate-package 1.8.0 → 1.9.0-0

package/README.md

@@ -105,7 +105,7 @@ If you are here to simplify and improve your Firebase deployments check out the
 
 ## Troubleshooting
 
-If something is not working as expected, add a `isolate.config.json` file, and
+If something is not working as expected, add an `isolate.config.json` file, and
 set `"logLevel"` to `"debug"`. This should give you detailed feedback in the
 console.
 
@@ -114,10 +114,7 @@ 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
-`DEBUG_ISOLATE_CONFIG=true npx isolate`
-
-If you do not pass in any configuration, the function will try to read a
-`isolate.config.json` file from disk. You can set
+`DEBUG_ISOLATE_CONFIG=true npx isolate`.
 
 ## Prerequisites
 
@@ -214,28 +211,40 @@ same location, as it uses the current working directory.
 
 Below you will find a description of every available option.
 
-### buildDirName
+### logLevel
 
-Type: `string | undefined`, default: `undefined`
+Type: `"info" | "debug" | "warn" | "error"`, default: `"info"`.
 
-The name of the build output directory name. When undefined it is automatically
-detected via `tsconfig.json`. When you are not using Typescript you can use this
-setting to specify where the build output files are located.
+Because the configuration loader depends on this setting, its output is not
+affected by this setting. If you want to debug the configuration set
+`DEBUG_ISOLATE_CONFIG=true` before you run `isolate`
 
-### excludeLockfile
+### useNpm
 
-Type: `boolean`, default: Depends on package manager.
+Type: `boolean`, default: `false`
 
-**Deprecated** This option exists from the time that lockfiles were not
-supported for all package managers. You should not need this escape hatch
-anymore.
+By default the isolate process will generate output based on the package manager
+that you are using for your monorepo. But your deployment target might not be
+compatible with that package manager, or it might not be the best choice given
+the available tooling.
 
-Sets the inclusion or exclusion of the lockfile as part of the deployment.
+Also, it should not really matter what package manager is used in de deployment
+as long as the versions match your original lockfile.
 
-Isolated / pruned lockfiles are generated for NPM, PNPM and Yarn v1 (classic)
-based on the existing root lockfile, and they are included by default.
+By setting this option to `true` you are forcing the isolate output to use NPM.
+A package-lock file will be generated based on the installed node modules and
+therefore should match the versions in your original lockfile.
 
-For more information see [lockfiles](#lockfiles).
+This way you can enjoy using PNPM for your monorepo, while your deployment uses
+NPM locked to the same versions.
+
+### buildDirName
+
+Type: `string | undefined`, default: `undefined`
+
+The name of the build output directory name. When undefined it is automatically
+detected via `tsconfig.json`. When you are not using Typescript you can use this
+setting to specify where the build output files are located.
 
 ### includeDevDependencies
 
@@ -245,19 +254,31 @@ By default devDependencies are ignored and stripped from the isolated output
 `package.json` files. If you enable this the devDependencies will be included
 and isolated just like the production dependencies.
 
-### isolateDirName
+### pickFromScripts
 
-Type: `string`, default: `"isolate"`
+Type: `string[]`, default: `undefined`
 
-The name of the isolate output directory.
+Select which scripts to include in the output manifest `scripts` field. For
+example if you want your test script included set it to `["test"]`.
 
-### logLevel
+By default, all scripts are omitted.
 
-Type: `"info" | "debug" | "warn" | "error"`, default: `"info"`.
+### omitFromScripts
 
-Because the configuration loader depends on this setting, its output is not
-affected by this setting. If you want to debug the configuration set
-`DEBUG_ISOLATE_CONFIG=true` before you run `isolate`
+Type: `string[]`, default: `undefined`
+
+Select which scripts to omit from the output manifest `scripts` field. For
+example if you want the build script interferes with your deployment target, but
+you want to preserve all of the other scripts, set it to `["build"]`.
+
+By default, all scripts are omitted, and the [pickFromScripts](#pickfromscripts)
+configuration overrules this configuration.
+
+### isolateDirName
+
+Type: `string`, default: `"isolate"`
+
+The name of the isolate output directory.
 
 ### targetPackagePath
 
@@ -323,31 +344,62 @@ When you use the `targetPackagePath` option, this setting will be ignored.
 
 ## Lockfiles
 
-A lockfile in a monorepo describes the dependencies of all packages, and does
-not translate to the isolated output without altering it.
+The isolate process tries to generate an isolated / pruned lockfile for the
+package manager that you use in your monorepo. If the package manager is not
+supported (modern Yarn versions), it can still generate a matching NPM lockfile
+based on the installed versions in node_modules.
+
+In case your package manager is not supported by your deployment target you can
+also choose NPM to be used by setting the `makeNpmLockfile` to `true` in your
+configuration.
+
+### NPM
+
+For NPM we use a tool called Arborist which is an integral part of the NPM
+codebase. It is executed in the isolate output directory and requires the
+adapted lockfile and the `node_modules` directory from the root of the
+repository. As this directory is typically quite large, copying it over as part
+of the isolate flow is not very desirable.
+
+To work around this, we move it to the isolate output and then move it back
+after Arborist has finished doing its thing. Luckily it doesn't take long and
+hopefully this doesn't create any unwanted side effects for IDEs and other tools
+that depend on the content of the directory.
+
+When errors occur in this process, the folder should still be moved back.
 
-If you copying the original lockfile and deploy it with the isolated code, a CI
-environment will not accept the lockfile. 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 negate the whole point of having a
-lockfile in the first place.
+### PNPM
 
-For this to work, we need to re-generate or prune the original lockfile to keep
-the versions of the original but only describe the dependencies of the code in
-the isolated output.
+The PNPM lockfile format is very readable (YAML) but getting it adapted to the
+isolate output was a bit of a trip.
 
-Since every package manager works completely different in this regard, this part
-of the puzzle had to be solved in a different ways for each of them, and not all
-are supported yet.
+It turns out, at least up to v10, that the isolated output has to be formatted
+as a workspace itself, otherwise dependencies of internally linked packages are
+not installed by PNPM. Therefore, the output looks a bit different from other
+package managers:
 
-At the moment lockfiles for the following package managers are supported:
+- Links are preserved
+- Versions specifiers like "workspace:\*" are preserved
+- A pnpm-workspace.yaml file is added to the output
 
-- NPM
-- PNPM
-- Yarn Classic (v1)
+### Classic Yarn
 
-More detailed information on the implementation can be found in the
-[additional docs](./docs/lockfiles.md).
+For Yarn v1 we can simply copy the root lockfile to the isolate output, and run
+a `yarn install` to prune that lockfile. The command finds the installed node
+modules in the root of the monorepo so versions are preserved.
+
+> Note: I expect this to break down if you configure the isolate output
+> directory to be located outside the monorepo tree.
+
+### Modern Yarn
+
+For modern Yarn versions we fall back to using NPM for the output lockfile,
+because the strategy of running `yarn install` does not seem to apply here.
+
+Based on the installed node_modules we generate an NPM lockfile that matches the
+versions in the Yarn lockfile. It should not really matter what package manager
+your deployed code uses, as long as the lockfile versions match with the
+original lockfile.
 
 ## API
 
@@ -365,6 +417,9 @@ await isolate({
 });
 ```
 
+If no configuration is passed in, the process will try to read
+`isolate.config.json` from the current working directory.
+
 ## The internal packages strategy
 
 An alternative approach to using internal dependencies in a Typescript monorepo

package/dist/index.d.ts

@@ -7,8 +7,9 @@ type IsolateConfigResolved = {
     tsconfigPath: string;
     workspacePackages?: string[];
     workspaceRoot: string;
-    excludeLockfile: boolean;
-    avoidPnpmPack: boolean;
+    useNpm: boolean;
+    pickFromScripts?: string[];
+    omitFromScripts?: string[];
 };
 type IsolateConfig = Partial<IsolateConfigResolved>;