Initial commit

skills/nix-packaging/js/claude-code/package.nix

@@ -0,0 +1,52 @@
+{
+  lib,
+  buildNpmPackage,
+  fetchzip,
+  nodejs_20,
+}:
+
+buildNpmPackage rec {
+  pname = "claude-code";
+  version = "2.0.21";
+
+  nodejs = nodejs_20; # required for sandboxed Nix builds on Darwin
+
+  src = fetchzip {
+    url = "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-${version}.tgz";
+    hash = "sha256-sX9btcy9uEHloAQNvCJFhwh0U/W14NWz2FjkdLXm1Q0=";
+  };
+
+  npmDepsHash = "sha256-LBc1M3FwWg6SP+p7GQ00LQfiYyhmU1OzsohDu6rukjA=";
+
+  postPatch = ''
+    cp ${./package-lock.json} package-lock.json
+  '';
+
+  dontNpmBuild = true;
+
+  AUTHORIZED = "1";
+
+  # `claude-code` tries to auto-update by default, this disables that functionality.
+  # https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#environment-variables
+  # The DEV=true env var causes claude to crash with `TypeError: window.WebSocket is not a constructor`
+  postInstall = ''
+    wrapProgram $out/bin/claude \
+      --set DISABLE_AUTOUPDATER 1 \
+      --unset DEV
+  '';
+
+  passthru.updateScript = ./update.sh;
+
+  meta = {
+    description = "Agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster";
+    homepage = "https://github.com/anthropics/claude-code";
+    downloadPage = "https://www.npmjs.com/package/@anthropic-ai/claude-code";
+    license = lib.licenses.unfree;
+    maintainers = with lib.maintainers; [
+      malo
+      markus1189
+      omarjatoi
+    ];
+    mainProgram = "claude";
+  };
+}

skills/nix-packaging/js/js.md

@@ -0,0 +1,102 @@
+# Package a JavaScript/TypeScript Application with Nix (npm)
+
+Packaging an npm application (`buildNpmPackage`) involves determining the package name, version, and dependencies. The package must be available on the npm registry.
+
+## Normal npm Package
+
+See the example: [claude-code](./claude-code/package.nix)
+
+Key components:
+
+- **Source**: Fetch from npm registry using `fetchzip` with URL pattern:
+  ```nix
+  url = "https://registry.npmjs.org/@scope/package-name/-/package-name-${version}.tgz";
+  ```
+  For non-scoped packages, omit the `@scope/` part.
+
+- **Dependencies**: Set `npmDepsHash` (see update workflow below for obtaining the hash)
+
+- **package-lock.json**: Use `postPatch` to copy a local `package-lock.json`:
+  ```nix
+  postPatch = ''
+    cp ${./package-lock.json} package-lock.json
+  '';
+  ```
+
+- **Build control**: Use `dontNpmBuild = true;` if the package doesn't require a build step (already built on npm registry)
+
+## Updating an Existing npm Package
+
+Besides the general update steps, also update npm-specific fields:
+
+1. **Update package-lock.json**: Generate a new lock file for the target version:
+
+   ```bash
+   # Find the latest version (or specific version)
+   npm i --package-lock-only @anthropic-ai/claude-code@"$version"
+   # Remove package.json (not needed for Nix packaging)
+   rm -f package.json
+   ```
+
+   **Note**: If `npm` is not installed, use `nix-shell` to run it:
+   ```bash
+   nix-shell -p nodejs --run "npm i --package-lock-only @anthropic-ai/claude-code@\"$version\""
+   rm -f package.json
+   ```
+
+   Copy the generated `package-lock.json` to your package directory.
+
+2. **Update hashes**: Both `hash` (source) and `npmDepsHash` need updating.
+
+   **Method 1: Let Nix tell you**
+   - Set `hash = "";` and run `nix build`. Copy the correct hash from the error message.
+   - Set `npmDepsHash = "";` and run `nix build`. Copy the correct hash from the error message.
+
+   **Method 2: Calculate directly**
+   ```bash
+   # For source hash
+   nix-prefetch-url --type sha256 --unpack https://registry.npmjs.org/@scope/package/-/package-${version}.tgz
+   nix hash convert --hash-algo sha256 <old-hash>
+   ```
+
+3. **Check for breaking changes**: New versions may:
+   - Change build requirements (update `dontNpmBuild` or add build dependencies)
+   - Require different Node.js versions (update `nodejs` attribute, e.g., `nodejs_20`)
+   - Add new environment variables or runtime requirements
+
+## Common Patterns
+
+### Specify Node.js Version
+
+For compatibility, especially on Darwin with sandboxed builds:
+
+```nix
+buildNpmPackage rec {
+  nodejs = nodejs_20;
+  # ...
+}
+```
+
+### Disable Auto-Build
+
+If the package is pre-built on the npm registry:
+
+```nix
+dontNpmBuild = true;
+```
+
+### Set Environment Variables
+
+Use `postInstall` to wrap the binary with required environment variables:
+
+```nix
+postInstall = ''
+  wrapProgram $out/bin/your-binary \
+    --set ENV_VAR value \
+    --unset UNWANTED_VAR
+'';
+```
+
+### Handle Optional Dependencies
+
+npm packages often have platform-specific optional dependencies (like Sharp's native bindings). These are automatically handled by `buildNpmPackage` based on the `package-lock.json`.