readme: add a basic flake usage example

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
index 874ae2b4b34..5e538e8447b 100644
--- a/README.md
+++ b/README.md
@@ -305,6 +305,60 @@ in your system configuration and
 
 in your Home Manager configuration.
 
+Flakes
+------
+
+Home Manager includes a flake.nix for compatibility with [NixOS flakes](https://nixos.wiki/wiki/Flakes) for those
+that wish to use it as a module. A bare-minimum flake.nix would be as follows:
+
+```nix
+{
+  description = "NixOS configuration";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    home-manager.url = "github:rycee/home-manager";
+  };
+
+  outputs = inputs: {
+    nixosConfigurations = {
+      hostname = let
+        system = "x86_64-linux";
+        pkgs = inputs.nixpkgs.legacyPackages.${system};
+        inherit (inputs.nixpkgs) lib;
+
+        # Things in this set are passed to modules and accessible
+        # in the top-level arguments (e.g. `{ pkgs, lib, inputs, ... }:`).
+        specialArgs = {
+          inherit inputs;
+        };
+
+        hm-nixos-as-super = { config, ... }: {
+          # Submodules have merge semantics, making it possible to amend
+          # the `home-manager.users` submodule for additional functionality.
+          options.home-manager.users = lib.mkOption {
+            type = lib.types.attrsOf (lib.types.submoduleWith {
+              modules = [ ];
+              # Makes specialArgs available to Home Manager modules as well.
+              specialArgs = specialArgs // {
+                # Allow accessing the parent NixOS configuration.
+                super = config;
+              };
+            });
+          };
+        };
+
+        modules = [
+          ./configuration.nix
+          inputs.home.nixosModules.home-manager
+          hm-nixos-as-super
+        ];
+      in lib.nixosSystem { inherit system modules specialArgs; };
+    };
+  };
+}
+```
+
 Releases
 --------