diff --git a/ISOLATED_BUILDS.md b/ISOLATED_BUILDS.md
new file mode 100644
index 0000000..47f2dc9
--- /dev/null
+++ b/ISOLATED_BUILDS.md
@@ -0,0 +1,50 @@
+# Isolated builds
+
+The configuration option `isolatedNixBuilds` adds the ability to create a
+separate Nix derivation for a dependency with a build step, which is then
+copied into your regular project build. This allows Nix to cache the dependency
+build, which is useful for e.g. large native code builds.
+
+As an example, to create an isolated build of sqlite3, add the following to
+your `.yarnrc.yml`:
+
+```yml
+isolatedNixBuilds: ["sqlite3"]
+```
+
+In your Nix expression, separate options can be set to override attributes of
+these derivations, which is often necessary to provide build inputs. For
+sqlite3, you'd do the following in your `default.nix`:
+
+```nix
+{ pkgs ? import <nixpkgs> { } }:
+
+pkgs.callPackage ./yarn-project.nix { } {
+  src = ./.;
+  overrideSqlite3Attrs = old: {
+    npm_config_sqlite = "/";  # Don't accidentally use the wrong sqlite.
+    buildInputs = old.buildInputs ++ (with pkgs; [ python3 sqlite ]);
+  };
+}
+```
+
+The general form of these options is `override<Package>Attrs` in camel-case.
+
+## Technical details
+
+For each package in `isolatedNixBuilds`, Nixify generates a derivation that
+installs just that package in a temporary directory. Nixify reuses only your
+Yarn bundle, your `yarn.lock` and a subset of your Yarn cache based on the
+dependency tree of the package. (These are also the inputs that, when changed,
+cause a rebuild.)
+
+In your final project build, each of these isolated builds are copied in, and
+Nixify tweaks the `.yarn/build-state.yml` file to hint Yarn it has already
+completed this build.
+
+## Limitations
+
+- `nodeLinker: node-modules` is unfortunately not supported at this time.
+
+- Peer dependencies are not considered, and isolated builds of packages with
+  peer dependencies are currently not well tested.
diff --git a/README.md b/README.md
index 23b0f50..97588e0 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # yarn-plugin-nixify
 
+**Upgrading the plugin? See [UPGRADING.md](./UPGRADING.md)**
+
 Generates a [Nix] expression to build a [Yarn] v2 project (not using
 zero-install).
 
@@ -129,6 +131,8 @@ Some additional settings are available in `.yarnrc.yml`:
   Preloading does mean another copy of dependencies on disk, even if you don't
   do local Nix builds, but the size is usually not an issue on modern disks.
 
+- `isolatedNixBuilds`, see [ISOLATED_BUILDS.md](./ISOLATED_BUILDS.md).
+
 [niv]: https://github.com/nmattia/niv
 
 ## Hacking
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000..719c849
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,59 @@
+# Upgrade notes
+
+This page lists significant changes to plugin functionality.
+
+Upgrading the plugin is the same procedure as installing:
+
+```sh
+# Install the plugin
+yarn plugin import https://raw.githubusercontent.com/stephank/yarn-plugin-nixify/main/dist/yarn-plugin-nixify.js
+
+# Run Yarn as usual
+yarn
+
+# Build your project with Nix
+nix-build
+```
+
+## Since 153254f (2021-04-30)
+
+- **BREAKING**: The generated `yarn-project.nix` now takes an attribute set:
+
+```nix
+# Before
+pkgs.callPackage ./yarn-project.nix { } ./.
+# After
+pkgs.callPackage ./yarn-project.nix { } { src = ./.; }
+```
+
+- **BREAKING**: The Yarn bundle and `yarn.lock` file are now directly
+  referenced by the generated Nix code as a path literal. This change should
+  not affect most regular Yarn installations, but may break if you're using a
+  specialized build of Yarn.
+
+- **BREAKING**: The derivations generated for downloading dependencies now have
+  slightly different names, based on the Yarn locator format instead of a
+  custom format. This unfortunately invalidates your Nix cache.
+
+- As a convenience, an `overrideAttrs` option has been added, but both methods
+  are still supported:
+
+```nix
+# Regular Nix-style:
+(pkgs.callPackage ./yarn-project.nix { } { src = ./.; })
+  .overrideAttrs (old: {
+    name = "foobar";
+  })
+
+# New option:
+pkgs.callPackage ./yarn-project.nix { } {
+  src = ./.;
+  overrideAttrs = old: {
+    name = "foobar";
+  };
+}
+```
+
+- It is now possible to isolate builds of dependencies, allowing more
+  fine-grained Nix cache. This is useful for e.g. modules with large native
+  code builds. See [ISOLATED_BUILDS.md](./ISOLATED_BUILDS.md).