Flake Docs (#909)

## Summary

Add Docs for our new Flake feature

## How was it tested?

Localhost

Author: Lagoja

docs/app/docs/configuration.md

@@ -25,6 +25,30 @@ This is a list of Nix packages that should be installed in your Devbox shell and
 
 You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using `devbox rm <package_name>`
 
+#### Adding Packages from Flakes
+
+You can add packages from flakes by adding a reference to the  flake in the `packages` list in your `devbox.json`. We currently support installing Flakes from Github and local paths.
+
+```json
+{
+    "packages": [
+        // Add the default package from a github repository 
+        "github:numtide/flake-utils",
+        // Install a specific attribute or package from a Github hosted flake
+        "github:nix-community/fenix#stable.toolchain", 
+        // Install a package from a specific channel of Nixpkgs
+        "github:nixos/nixpkgs/21.05#hello",
+        // Install a package form a specific commit of Nixpkgs
+        "github:nixos/nixpkgs/5233fd2ba76a3accb5aaa999c00509a11fd0793c#hello",
+        // Install a package from a local flake. This should point to a directory that contains a flake.nix file.
+        "path:../my-flake#my-package"
+    ]
+}
+```
+
+To learn more about using flakes, see the [Using Flakes](guides/using_flakes.md) guide.
+
+
 ### Env
 
 This is a a map of key-value pairs that should be set as Environment Variables when activating `devbox shell`, running a script with `devbox run`, or starting a service. These variables will only be set in your Devbox shell, and will have precedence over any environment variables set in your local machine or by [Devbox Plugins](guides/plugins.md).

docs/app/docs/guides/pinning_packages.md

@@ -6,11 +6,12 @@ This doc will explain how to select and pin specific package versions in Devbox
 
 ## Background
 
-The Nix Package Manager, which Devbox uses to install your shell packages, stores it's package definitions in a Github Repository at [NixOS/nixpkgs](https://github.com/NixOS/nixpkgs). This repository contains the Nix build definitions for over 80,000 different packages. New packages or changes to build definitions are added (and deprecated packages are removed) by committing to the repo. 
+The Nix Package Manager, which Devbox uses to install your shell packages, stores its package definitions in a Github Repository at [NixOS/nixpkgs](https://github.com/NixOS/nixpkgs). This repository contains instructions for building over 80,000 different packages. Maintainers add new packages or remove deprecated packages by committing to the repo. 
 
-Because Nix uses Git to store it's package definitions, we can install specific packages from older versions of the Nix Store by specifying the commit that we want to use. You can also use this commit to pin your project to a specific version of Nixpkgs, so that any developer using your project will get the exact same packages. 
+Because Nix uses Git to store its package definitions, we can install specific packages from older versions of the Nix Store by specifying the default commit we want to use. You can also use this commit to pin your project to a specific version of Nixpkgs, so any developer using your project will get the same packages. 
 
-## Pinning the Nixpkg commit in your Devbox.json
+
+## Pinning the Default Nixpkg commit in your Devbox.json
 
 Devbox stores the Nixpkg commit in your project's `devbox.json`, under the `nixpkgs.commit`. If you do not specify one in your config, Devbox will automatically add a default commit hash when you run a command like `devbox add`, `devbox shell`, or `devbox run`:
 
@@ -25,11 +26,24 @@ This hash ensures that Devbox will install the same packages whenever you start
 
 To use the latest available packages in Nix, you can replace the commit in `devbox.json` with the latest `nixpkgs-unstable` hash from [https://status.nixos.org](https://status.nixos.org). 
 
-## Look up a commit hash for a specific package
+## Pinning a Nixpkg Commit for a Single Package
+
+If you want to use a different commit for a single package, you can use a Flake reference to use an older revision of Nixpkg for just that package. The example below shows how to install the `hello` package from a specific Nixpkg commit:
+
+```json
+}
+	"packages" : [
+"github:nixos/nixpkgs/5233fd2ba76a3accb5aaa999c00509a11fd0793c#hello"
+	]
+}
+```
+Note that using a different nixpkg commit may install some duplicate packages and cause Nix Store bloat, so use this option sparingly. 
+
+## How to Find the Nixpkg Commit for a Package
 
-In most cases, the packages available in Devbox's default commit should suffice for your use cases. However, if you need a specific minor version, or an older version of a package that is no longer included in Nixpkgs, you may need update the commit SHA. Unfortunately, Nix does not have an official way to find the Nixpkg commit SHA for a specific version of a package. 
+In most cases, the packages available in Devbox's default commit should suffice for your use cases. However, if you want to install an older package no longer available in Nix, you must use an older commit reference in either your Flake reference or default nixpkg commit.
 
-However, there is an unofficial search tool at [https://lazamar.co.uk/nix-versions/](https://lazamar.co.uk/nix-versions/) that can be used to list the Nixpkg commits for different versions of a specific package. To find the correct Nixpkg commit hash: 
+Unfortunately, Nix does not have an official way to find the Nixpkg commit SHA for a specific package. However, an unofficial search tool at [https://lazamar.co.uk/nix-versions/](https://lazamar.co.uk/nix-versions/) can be used to list the Nixpkg commits for different versions of a specific package. To find the correct Nixpkg commit hash: 
 1. Select `nixpkgs-unstable` in the dropdown
 2. Enter the name of the package you want to search, and hit Search
 3. In the search results, find the version you want in the Version Column

docs/app/docs/guides/using_flakes.md

@@ -0,0 +1,90 @@
+---
+title: Using Packages from Nix Flakes
+---
+
+Devbox supports installing packages with [Nix Flakes](https://nixos.wiki/wiki/Flakes). While Nixpkgs is a great
+
+Devbox currently provides two ways to use Flakes to install packages in your project: 
+
+1. You can reference a Flake hosted in Github using the `github:` reference
+2. You can reference a local Flake using the `path:` reference
+
+## What are Flakes?
+
+[Flakes](https://www.jetpack.io/blog/powered-by-flakes/) are a new feature in the Nix language that lets us package software and create development shells in a declarative, fully reproducible way. You can use Nix Flakes to define packages, apps, templates, and dev environments. 
+
+Flakes are defined as a directory with a `flake.nix` and a `flake.lock` file. You import flakes to your project using a flake reference, which describes where to find the Flake, and what version or revision to use
+
+## Using a Flake from Github
+
+You can add a Flake hosted on Github using the following string in your packages list: 
+
+```json
+"packages": [
+    "github:<org>/<repo>/<ref>#<optional_flake_attr>"
+]
+```
+
+The Ref and Flake Attribute is optional and will default to the main branch and `packages.default|defaultPackage` attribute, respectively.
+
+For example, to install [Process Compose](https://github.com/F1bbonac1/process-compose) from its repository using Nix Flakes, you can use the following string in your packages list. This will install the latest version of Process Compose from the `main` branch.
+
+```nix
+github:F1bbonac1/process-compose
+```
+
+### Installing a Flake from a specific branch or tag
+
+You can install a specific release or branch by adding it to your flake reference. The following example will install Process Compose version 0.40.2 from the `v0.40.2` tag.
+
+```nix
+github:F1bbonac1/process-compose/v0.40.2
+```
+
+### Installing a specific attribute or package from a Flake
+
+You can also install a specific attribute or package from a Flake by adding a `#` and the attribute name to the end of the package string. If you don't specify an attribute, Devbox will use `default` or `defaultPackage`
+
+For example, if you want to use [Fenix](https://github.com/nix-community/fenix) to install a specific version of Nix, you can use the following string in your packages list. This example will install the `stable.toolchain` packages from the `fenix` package.
+
+```nix
+github:nix-community/fenix#stable.toolchain
+```
+
+### Using Flakes with Nixpkgs
+
+The Nixpkgs repo on Github also provides a Flake for installing packages. You can use the following flake reference to install packages from a specific Nixpkgs commit or reference:
+
+```nix
+github:NixOS/nixpkgs/<ref>#<package>
+```
+
+For example, if you want to install the `hello` package from the `nixos-20.09` branch, you can use the following string in your packages list:
+
+```nix
+github:NixOS/nixpkgs/nixos-20.09#hello
+```
+
+## Using a Local Flake
+
+You can also use a local Flake using the `path` attribute in your package list. Using a local flake can be helpful if you want to install your custom packages with Nix, or if you need to modify packages before using them in your Devbox project
+
+Your flake reference should point to a directory that contains a `flake.nix` file.
+
+```nix
+path:<path_to_flake>#<optional_flake_attr>
+```
+
+For example, if you have a local Flake in the `./my-flake` directory, you can use the following string in your `packages` list. This example will install all the packages under the `my-package` attribute.
+
+```nix
+path:./my-flake#my-package
+```
+
+### Examples
+
+For more examples of using Nix Flakes with Devbox, check out the examples in our Devbox Repo:
+
+- [Using Nix Flakes from Github](https://github.com/jetpack-io/devbox/tree/main/examples/flakes/remote)
+- [Using a Local Flake](https://github.com/jetpack-io/devbox/tree/main/examples/flakes/php)
+- [Applying an Overlay with Nix Flakes](https://github.com/jetpack-io/devbox/tree/main/examples/flakes/overlay)

docs/app/sidebars.js

@@ -53,6 +53,9 @@ const sidebars = {
         }, {
             type: 'doc',
             id: 'guides/services'
+        }, {
+            type: 'doc',
+            id: 'guides/using_flakes'
         }]
     }, {
         type: 'category',

examples/flakes/README.md

@@ -2,7 +2,7 @@
 
 Examples that show how to add custom flakes to your devbox project.
 
-# Local flakes (usually committed to your project)
+## Local flakes (usually committed to your project)
 
 In devbox.json use "path:/path/to/flake#output" as the package name.
 
@@ -23,6 +23,24 @@ In devbox.json use "path:/path/to/flake#output" as the package name.
 
 This installs the "php" and "hello" outputs from the flake at `my-php-flake`. These outputs can also be part of packages or legacyPackages.
 
-# Remote flakes
+## Remote flakes
 
-TODO
+Use `github:<org>/<repo>/<ref>#<output>` as the package name to install from a Github repo.
+
+```json
+{
+  "packages": [
+    "github:nixos/nixpkgs/5233fd2ba76a3accb5aaa999c00509a11fd0793c#hello",
+    "github:nix-community/fenix#stable.toolchain",
+    "github:F1bonacc1/process-compose"
+  ],
+  "shell": {
+    "init_hook": null
+  },
+  "nixpkgs": {
+    "commit": "f80ac848e3d6f0c12c52758c0f25c10c97ca3b62"
+  }
+}
+```
+
+This installs the `hello` package from the 5233fd... commit of Nixpkgs, the `stable.toolchain` output from the `fenix` package in the `nix-community/fenix` repo, and the `default` output from the `F1bonacc1/process-compose` repo.

examples/flakes/overlay/.nvmrc

@@ -0,0 +1 @@
+16

examples/flakes/overlay/README.md

@@ -0,0 +1,28 @@
+# Adding Overlays with Flakes
+
+This flake shows how to use an overlay Nix flake to override a Nixpkgs package and use it in your devbox configuration.
+
+In this example, using the default `yarn` from Nixpkgs will cause `yarn start` to fail. To fix this issue, we use an overlay to modify the `yarn` package to use NodeJS 16 instead of it's default NodeJS 14.
+
+```nix
+
+   overlay = (final: prev: {
+      yarn = prev.yarn.override { nodejs = final.pkgs.nodejs-16_x; };
+   });
+```
+
+The yarn-overlay flake exports the modified yarn package in it's outputs. We can then use this package in our devbox shell by adding it to `packages` in our `devbox.json` file.
+
+```json
+{
+   "packages": [
+      "path:./yarn-overlay#yarn"
+      "fnm"
+   ]
+   ...
+}
+```
+
+Note: you will need Devbox 0.4.7-dev or later for this to work. You can try it out by exporting `DEVBOX_VERSION=0.4.7-dev` before running `devbox shell`.
+
+You can use the flake.nix in the yarn-overlay directory as a template for creating your own overlays.

examples/flakes/overlay/devbox.json

@@ -0,0 +1,14 @@
+{
+  "packages": [
+    "fnm",
+    "path:yarn-overlay#yarn"
+  ],
+  "shell": {
+    "init_hook": [
+      "eval \"$(fnm env --use-on-cd)\""
+    ]
+  },
+  "nixpkgs": {
+    "commit": "eabc38219184cc3e04a974fe31857d8e0eac098d"
+  }
+}

examples/flakes/overlay/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "nix-yarn-issue",
+  "version": "1.0.0",
+  "license": "MIT",
+  "scripts": {
+    "start": "echo 'it should run'"
+  },
+  "engines": {
+    "node": ">= 16"
+  }
+}