diff --git a/.envrc b/.envrc
new file mode 100644
index 00000000..a5dbbcba
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake .
diff --git a/.gitignore b/.gitignore
index 8960c0ec..11b1f504 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,4 +58,7 @@ packages/react-devtools-extensions/.tempUserDataDir
 out
 
 # Cursor files
-.cursorrules
\ No newline at end of file
+.cursorrules
+
+# direnv local cache (committed: .envrc)
+.direnv
\ No newline at end of file
diff --git a/README.md b/README.md
index 08874f96..8d7a0d05 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,36 @@ An Electron application with React and TypeScript
 
 ## Project Setup
 
-### Install
+### Using Nix (Recommended for NixOS users)
+
+With [direnv](https://direnv.net/) and [nix-direnv](https://github.com/nix-community/nix-direnv):
+
+```bash
+direnv allow   # one-time, auto-loads the flake on every cd
+npm install
+npm run dev
+```
+
+Without direnv:
+
+```bash
+nix develop
+npm install
+npm run dev
+```
+
+The flake provides a NixOS-patched Electron binary via `ELECTRON_EXEC_PATH`,
+so no `LD_LIBRARY_PATH` exports are needed.
+
+### Manual Setup
+
+#### Install
 
 ```bash
 $ npm install
 ```
 
-### Development
+#### Development
 
 ```bash
 $ npm run dev
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 00000000..6908e251
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1776877367,
+        "narHash": "sha256-EHq1/OX139R1RvBzOJ0aMRT3xnWyqtHBRUBuO1gFzjI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "0726a0ecb6d4e08f6adced58726b95db924cef57",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 00000000..7bea0fda
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,26 @@
+{
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs =
+    { nixpkgs, ... }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system});
+    in
+    {
+      devShells = forAllSystems (pkgs: {
+        default = pkgs.mkShell {
+          packages = [ pkgs.nodejs pkgs.electron ];
+          # Use the NixOS-patched Electron instead of the pre-built npm binary.
+          # pkgs.electron has correct RPATHs baked in, supports native Wayland
+          # (ozone/Chromium), and needs no LD_LIBRARY_PATH workarounds.
+          # electron-vite reads ELECTRON_EXEC_PATH before falling back to
+          # node_modules/electron/dist/electron.
+          ELECTRON_EXEC_PATH = "${pkgs.electron}/bin/electron";
+        };
+      });
+    };
+}