lockfile-subset 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tmokmss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# lockfile-subset
+
+Extract a subset of `package-lock.json` for specified packages and their transitive dependencies.
+
+## Why?
+
+When using bundlers like esbuild with `--external`, you need to ship those external packages separately (e.g., in a Docker multi-stage build or Lambda layer). Getting the exact right set of dependencies is surprisingly hard:
+
+| Approach | Problem |
+|---|---|
+| Manually copy `node_modules` dirs | Breaks when transitive deps change (e.g., Prisma v6 added new deps) |
+| `npm install <pkg>` in runner stage | Resolves versions independently — may differ from your lockfile |
+| `npm ci --omit=dev` | Installs *all* prod dependencies, not just the ones you need |
+
+**lockfile-subset** solves this by extracting a precise subset from your existing `package-lock.json` — only the packages you specify and their transitive dependencies, with versions exactly matching the original lockfile.
+
+## Install
+
+```bash
+npm install -g lockfile-subset
+# or use directly with npx
+npx lockfile-subset
+```
+
+## Usage
+
+```bash
+# Extract @prisma/client and sharp with their transitive deps
+lockfile-subset @prisma/client sharp
+
+# Specify output directory
+lockfile-subset @prisma/client sharp -o /standalone
+
+# Use a different lockfile path
+lockfile-subset @prisma/client sharp --lockfile /build/package-lock.json
+
+# Generate + install in one step
+lockfile-subset @prisma/client sharp -o /standalone --install
+
+# Preview without writing files
+lockfile-subset prisma --dry-run
+```
+
+This generates a minimal `package.json` and `package-lock.json` in the output directory. Then run `npm ci` to install exactly those packages at the exact versions from your original lockfile.
+
+### Dockerfile example
+
+```dockerfile
+# === Builder ===
+FROM node AS builder
+WORKDIR /build
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npx esbuild src/index.ts --bundle --outdir=dist \
+    --external:@prisma/client --external:sharp
+
+# Generate subset lockfile + install
+RUN npx lockfile-subset @prisma/client sharp \
+    -o /standalone --install
+
+# === Runner ===
+FROM node AS runner
+WORKDIR /app
+
+# Only the packages you need, at exact lockfile versions
+COPY --from=builder /standalone/node_modules ./node_modules
+COPY --from=builder /build/dist ./dist
+
+CMD ["node", "dist/index.js"]
+```
+
+### Options
+
+```
+lockfile-subset <packages...> [options]
+
+Arguments:
+  packages                  Package names to extract (space-separated)
+
+Options:
+  --lockfile, -l <path>     Path to project directory (default: .)
+  --output, -o <dir>        Output directory (default: ./lockfile-subset-output)
+  --no-optional             Exclude optional dependencies
+  --install                 Run npm ci after generating the subset
+  --dry-run                 Print the result without writing files
+  --version, -v             Show version
+  --help, -h                Show help
+```
+
+## How it works
+
+1. Loads your `package-lock.json` using [`@npmcli/arborist`](https://github.com/npm/cli/tree/latest/workspaces/arborist) (npm's own dependency resolver)
+2. Starting from the specified packages, walks the dependency tree via BFS to collect all transitive dependencies
+3. Copies the matching entries from the original lockfile — no re-resolution, no version drift
+4. Outputs a minimal `package.json` + `package-lock.json` ready for `npm ci`
+
+Dev dependencies of each package are excluded from traversal. Optional dependencies are included by default (use `--no-optional` to exclude).
+
+## Limitations
+
+- **npm only** — pnpm and yarn have different lockfile formats. pnpm users can use `pnpm deploy`; yarn users can use `yarn workspaces focus`.
+- **Platform-specific optional deps** — Packages like `sharp` have OS/arch-specific optional dependencies (e.g., `@img/sharp-linux-x64`). If your lockfile was generated on macOS but you run `npm ci` on Linux (e.g., in Docker), those Linux-specific packages may be missing from the lockfile. In that case, generate the lockfile on the target platform, or use `npm install` instead of `npm ci`.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/index.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { join, resolve } from "path";
+import { execSync } from "child_process";
+import { createRequire } from "module";
+import Arborist from "@npmcli/arborist";
+import { mkdirSync, writeFileSync } from "fs";
+//#region src/extract.ts
+async function extractSubset({ projectPath, packageNames, includeOptional = true }) {
+	const tree = await new Arborist({ path: projectPath }).loadVirtual();
+	const keep = /* @__PURE__ */ new Set();
+	for (const name of packageNames) {
+		const edge = tree.edgesOut.get(name);
+		if (!edge?.to) throw new Error(`Package "${name}" not found in lockfile`);
+		const queue = [edge.to];
+		while (queue.length > 0) {
+			const node = queue.shift();
+			if (keep.has(node)) continue;
+			keep.add(node);
+			for (const e of node.edgesOut.values()) {
+				if (e.type === "dev") continue;
+				if (e.type === "optional" && !includeOptional) continue;
+				if (e.to && !keep.has(e.to)) queue.push(e.to);
+			}
+		}
+	}
+	const dependencies = {};
+	for (const name of packageNames) dependencies[name] = tree.edgesOut.get(name).to.version;
+	const subsetPackages = {};
+	subsetPackages[""] = {
+		name: "lockfile-subset-output",
+		version: "1.0.0",
+		dependencies
+	};
+	const originalPackages = tree.meta.data.packages;
+	for (const node of keep) {
+		const location = node.location;
+		if (originalPackages[location]) subsetPackages[location] = originalPackages[location];
+	}
+	const collected = [...keep].map((node) => ({
+		name: node.name,
+		version: node.version,
+		location: node.location
+	}));
+	return {
+		packageJson: {
+			name: "lockfile-subset-output",
+			version: "1.0.0",
+			dependencies
+		},
+		lockfileJson: {
+			name: "lockfile-subset-output",
+			version: "1.0.0",
+			lockfileVersion: 3,
+			requires: true,
+			packages: subsetPackages
+		},
+		collected
+	};
+}
+//#endregion
+//#region src/write.ts
+function writeOutput(outputDir, result) {
+	mkdirSync(outputDir, { recursive: true });
+	writeFileSync(join(outputDir, "package.json"), JSON.stringify(result.packageJson, null, 2) + "\n");
+	writeFileSync(join(outputDir, "package-lock.json"), JSON.stringify(result.lockfileJson, null, 2) + "\n");
+}
+//#endregion
+//#region src/index.ts
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+function parseArgs(argv) {
+	const args = {
+		packages: [],
+		lockfile: ".",
+		output: "./lockfile-subset-output",
+		includeOptional: true,
+		install: false,
+		dryRun: false,
+		help: false,
+		version: false
+	};
+	let i = 0;
+	while (i < argv.length) {
+		const arg = argv[i];
+		switch (arg) {
+			case "--lockfile":
+			case "-l":
+				args.lockfile = argv[++i];
+				break;
+			case "--output":
+			case "-o":
+				args.output = argv[++i];
+				break;
+			case "--no-optional":
+				args.includeOptional = false;
+				break;
+			case "--install":
+				args.install = true;
+				break;
+			case "--dry-run":
+				args.dryRun = true;
+				break;
+			case "--help":
+			case "-h":
+				args.help = true;
+				break;
+			case "--version":
+			case "-v":
+				args.version = true;
+				break;
+			default:
+				if (arg.startsWith("-")) {
+					console.error(`Unknown option: ${arg}`);
+					process.exit(1);
+				}
+				args.packages.push(arg);
+		}
+		i++;
+	}
+	return args;
+}
+const HELP = `
+lockfile-subset <packages...> [options]
+
+Extract a subset of package-lock.json for specified packages and their transitive dependencies.
+
+Arguments:
+  packages                  Package names to extract (one or more, space-separated)
+
+Options:
+  --lockfile, -l <path>     Path to project dir or package-lock.json (default: .)
+  --output, -o <dir>        Output directory (default: ./lockfile-subset-output)
+  --no-optional             Exclude optional dependencies
+  --install                 Run npm ci after generating the subset
+  --dry-run                 Print the result without writing files
+  --version, -v             Show version
+  --help, -h                Show this help
+
+Examples:
+  lockfile-subset prisma sharp
+  lockfile-subset prisma sharp -o /lambda-standalone
+  lockfile-subset prisma sharp --lockfile /build/package-lock.json
+  lockfile-subset prisma sharp -o /lambda-standalone --install
+  lockfile-subset prisma --dry-run
+`.trim();
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.version) {
+		console.log(VERSION);
+		return;
+	}
+	if (args.help) {
+		console.log(HELP);
+		return;
+	}
+	if (args.packages.length === 0) {
+		console.error("Error: At least one package name is required.\n");
+		console.log(HELP);
+		process.exit(1);
+	}
+	const projectPath = resolve(args.lockfile);
+	const outputDir = resolve(args.output);
+	const result = await extractSubset({
+		projectPath,
+		packageNames: args.packages,
+		includeOptional: args.includeOptional
+	});
+	console.log(`Collected ${result.collected.length} packages (${args.packages.length} direct, ${result.collected.length - args.packages.length} transitive)`);
+	if (args.dryRun) {
+		console.log("\n--- package.json ---");
+		console.log(JSON.stringify(result.packageJson, null, 2));
+		console.log("\n--- package-lock.json ---");
+		console.log(JSON.stringify(result.lockfileJson, null, 2));
+		return;
+	}
+	writeOutput(outputDir, result);
+	console.log(`Written to ${outputDir}`);
+	if (args.install) {
+		console.log("Running npm ci...");
+		execSync("npm ci", {
+			cwd: outputDir,
+			stdio: "inherit"
+		});
+		console.log("Done.");
+	}
+}
+main().catch((err) => {
+	console.error(`Error: ${err.message}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "lockfile-subset",
+  "version": "1.0.0",
+  "description": "Extract a subset of package-lock.json for specified packages and their transitive dependencies",
+  "type": "module",
+  "bin": {
+    "lockfile-subset": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "npm",
+    "lockfile",
+    "package-lock",
+    "subset",
+    "docker",
+    "dependencies"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tmokmss/lockfile-subset.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.5.0",
+    "@types/npmcli__arborist": "^6.3.3",
+    "semantic-release": "^25.0.3",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@npmcli/arborist": "^9.4.2"
+  }
+}