docs: nix lib.bundle

docs/guide/nix.md

@@ -1,8 +1,94 @@
 # Usage on NixOS
 
-The recommended way is to use the home-manager module.
+Initialize a directory using the template.
+
+```sh
+nix flake init --template github:aylur/ags
+```
+
+## Bundle and DevShell
+
+The flake exposes a `lib.bundle` function which can bundle your projects.
+Using nix, you'll technically never have to use the `ags` cli.
+
+:::code-group
+
+```nix [<i class="devicon-nixos-plain"></i> flake.nix]
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+    ags.url = "github:aylur/ags";
+  };
+
+  outputs = { self, nixpkgs, ags }: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+  in {
+    packages.${system}.default = ags.lib.bundle { # [!code focus:12]
+      inherit pkgs;
+      src = ./.;
+      name = "my-shell"; # name of executable
+      entry = "app.ts";
+
+      # additional libraries and executables to add to gjs' runtime
+      extraPackages = [
+        # ags.packages.${system}.battery
+        # pkgs.fzf
+      ];
+    };
+  };
+}
+```
+
+:::
+
+While working on the project, it would make sense to use the `ags` cli
+instead of building it everytime with `nix`.
+
+You could enter a shell with `agsFull` package which
+exposes AGS + every [Astal library](https://aylur.github.io/astal/guide/libraries/references#astal-libraries).
+
+```sh
+nix shell github:aylur/ags#agsFull
+```
+
+Or define a `devShell` and cherry pick packages.
+
+:::code-group
+
+```nix [<i class="devicon-nixos-plain"></i> flake.nix]
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+    ags.url = "github:aylur/ags";
+  };
+
+  outputs = { self, nixpkgs, ags }: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+  in {
+    devShells.${system}.default = pkgs.mkShell {
+      buildInputs = [
+        # includes astal3 astal4 astal-io by default
+        (ags.packages.${system}.default.overrideAttrs { # [!code focus:5]
+          extraPackages = [
+            # cherry pick packages
+          ];
+        })
+      ];
+    };
+  };
+}
+```
+
+## Using home-manager
+
+If you prefer the workflow of AGS v1, you can use the home-manager module.
+
+:::
+
+Example content of `flake.nix`
 
-Example content of a `flake.nix` file that contains your `homeConfigurations`.
 :::code-group
 
 ```nix [<i class="devicon-nixos-plain"></i> flake.nix]
@@ -14,8 +100,7 @@ Example content of a `flake.nix` file that contains your `homeConfigurations`.
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # add ags https://github.com/Aylur/ags/pull/504
-    ags.url = "github:aylur/ags/v2";
+    ags.url = "github:aylur/ags"; # [!code focus]
   };
 
   outputs = { home-manager, nixpkgs, ... }@inputs:
@@ -26,18 +111,17 @@ Example content of a `flake.nix` file that contains your `homeConfigurations`.
     homeConfigurations."${username}" = home-manager.lib.homeManagerConfiguration {
       pkgs = import nixpkgs { inherit system; };
 
-      # pass inputs as specialArgs
+      # pass inputs as specialArgs # [!code focus:2]
       extraSpecialArgs = { inherit inputs; };
 
-      # import your home.nix
+      # import your home.nix # [!code focus:2]
       modules = [ ./home-manager/home.nix ];
     };
   };
 }
 ```
 
 :::
-
 Example content of `home.nix` file
 
 :::code-group
@@ -50,6 +134,8 @@ Example content of `home.nix` file
 
   programs.ags = {
     enable = true;
+
+    # symlink to ~/.config/ags
     configDir = ../ags;
 
     # additional packages to add to gjs's runtime
@@ -63,7 +149,7 @@ Example content of `home.nix` file
 
 :::
 
-AGS by default only includes the core `astal3`, `astal4` and `astal-io` libraries.
+The module only includes the core `astal3`, `astal4` and `astal-io` libraries.
 If you want to include any other [library](https://aylur.github.io/astal/guide/libraries/references#astal-libraries) you have to add them to `extraPackages`.
 You can also add binaries which will be added to the gjs runtime.
 
@@ -72,7 +158,10 @@ The `configDir` option symlinks the given path to `~/.config/ags`.
 If you already have your source code there leave it as `null`.
 :::
 
-The AGS flake does not expose the `astal` cli to the home environment, you have to do that yourself if you want:
+## Using Astal CLI tools
+
+The home-manager module does not expose the `astal` cli to the home environment,
+you have to do that yourself if you want:
 
 :::code-group
 

docs/vitepress.config.ts

@@ -36,6 +36,7 @@ export default defineConfig({
             { text: "Generating types", link: "/guide/types" },
             { text: "Astal CLI", link: "/guide/astal-cli" },
             { text: "Example", link: "/guide/example" },
+            { text: "Nix", link: "/guide/nix" },
         ],
 
         socialLinks: [

flake.nix

@@ -44,7 +44,7 @@
       welcomeText = ''
         # Getting Started
         - run `nix develop` to enter the development environment
-        - run `ags init -f` to setup an initial ags project
+        - run `ags init . -f` to setup an initial ags project
         - run `ags run .`   to run the project
       '';
     };