detect-monorepo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Thijs Koerselman
+
+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,68 @@
+# detect-monorepo
+
+A tiny, zero-dependency helper that walks upward from a starting directory to
+decide whether it sits inside a JS/TS monorepo workspace.
+
+It recognises:
+
+- pnpm workspaces (`pnpm-workspace.yaml`)
+- npm, yarn, and bun workspaces (`workspaces` field in `package.json`)
+- Rush (`rush.json`)
+
+It is intended for tools that need a cheap pre-check before loading heavier
+monorepo tooling — for example,
+[`isolate-package`](https://github.com/0x80/isolate-package) is only useful
+inside a monorepo, so consumers like
+[`firebase-tools-with-isolate`](https://github.com/0x80/firebase-tools-with-isolate)
+can call `detectMonorepo` first and only pay the cost of loading
+`isolate-package` when a workspace is actually detected.
+
+## Install
+
+```sh
+pnpm add detect-monorepo
+# or
+npm install detect-monorepo
+```
+
+## Usage
+
+```ts
+import { detectMonorepo } from "detect-monorepo";
+
+const info = detectMonorepo();
+// or pass an explicit start directory:
+const info = detectMonorepo("/path/to/some/package");
+
+if (info) {
+  console.log(`Monorepo detected at ${info.rootDir} (kind: ${info.kind})`);
+} else {
+  console.log("Not inside a monorepo");
+}
+```
+
+The function returns either `null` or:
+
+```ts
+type MonorepoInfo = {
+  /** Absolute path to the monorepo workspace root. */
+  rootDir: string;
+  /** Which workspace marker was found. "workspaces" covers npm/yarn/bun. */
+  kind: "pnpm" | "workspaces" | "rush";
+};
+```
+
+## Behaviour
+
+- Walks upward from `startDir` (default: `process.cwd()`) up to four levels
+  (the start directory plus three parents), stopping at the filesystem root
+  if reached earlier.
+- Returns the first match found while walking upward.
+- A `package.json` that cannot be parsed, or one whose `workspaces` field
+  isn't an array or a `{ packages: string[] }` object, is treated as "no
+  workspace marker here" — the walk continues upward.
+- Requires Node.js 20 or newer.
+
+## License
+
+MIT © Thijs Koerselman

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+//#region src/detect-monorepo.d.ts
+type MonorepoInfo = {
+  /** Absolute path to the monorepo workspace root. */rootDir: string; /** Which workspace marker was found. "workspaces" covers npm/yarn/bun. */
+  kind: "pnpm" | "workspaces" | "rush";
+};
+/**
+ * Walk upward from `startDir` looking for a monorepo workspace root. Returns
+ * null if none is found within `MAX_DEPTH` levels (startDir itself plus three
+ * parents) or before reaching the filesystem root.
+ *
+ * Supported markers:
+ * - `pnpm-workspace.yaml`
+ * - `package.json` containing a `workspaces` field (npm, yarn, bun)
+ * - `rush.json`
+ */
+declare function detectMonorepo(startDir?: string): MonorepoInfo | null;
+//#endregion
+export { type MonorepoInfo, detectMonorepo };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/detect-monorepo.ts
+const MAX_DEPTH = 4;
+/**
+* Walk upward from `startDir` looking for a monorepo workspace root. Returns
+* null if none is found within `MAX_DEPTH` levels (startDir itself plus three
+* parents) or before reaching the filesystem root.
+*
+* Supported markers:
+* - `pnpm-workspace.yaml`
+* - `package.json` containing a `workspaces` field (npm, yarn, bun)
+* - `rush.json`
+*/
+function detectMonorepo(startDir = process.cwd()) {
+	let current = path.resolve(startDir);
+	for (let i = 0; i < MAX_DEPTH; i++) {
+		if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) return {
+			rootDir: current,
+			kind: "pnpm"
+		};
+		if (fs.existsSync(path.join(current, "rush.json"))) return {
+			rootDir: current,
+			kind: "rush"
+		};
+		const pkgPath = path.join(current, "package.json");
+		if (fs.existsSync(pkgPath)) try {
+			if (hasWorkspacesField(JSON.parse(fs.readFileSync(pkgPath, "utf8")).workspaces)) return {
+				rootDir: current,
+				kind: "workspaces"
+			};
+		} catch {}
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+}
+/**
+* Accepts either an array of globs or a Yarn-style object with a `packages`
+* array. Anything else is treated as not a workspace root.
+*/
+function hasWorkspacesField(value) {
+	if (Array.isArray(value)) return true;
+	if (typeof value === "object" && value !== null) {
+		const packages = value.packages;
+		return Array.isArray(packages);
+	}
+	return false;
+}
+//#endregion
+export { detectMonorepo };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/detect-monorepo.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n\nexport type MonorepoInfo = {\n  /** Absolute path to the monorepo workspace root. */\n  rootDir: string;\n  /** Which workspace marker was found. \"workspaces\" covers npm/yarn/bun. */\n  kind: \"pnpm\" | \"workspaces\" | \"rush\";\n};\n\nconst MAX_DEPTH = 4;\n\n/**\n * Walk upward from `startDir` looking for a monorepo workspace root. Returns\n * null if none is found within `MAX_DEPTH` levels (startDir itself plus three\n * parents) or before reaching the filesystem root.\n *\n * Supported markers:\n * - `pnpm-workspace.yaml`\n * - `package.json` containing a `workspaces` field (npm, yarn, bun)\n * - `rush.json`\n */\nexport function detectMonorepo(\n  startDir: string = process.cwd(),\n): MonorepoInfo | null {\n  let current = path.resolve(startDir);\n  for (let i = 0; i < MAX_DEPTH; i++) {\n    if (fs.existsSync(path.join(current, \"pnpm-workspace.yaml\"))) {\n      return { rootDir: current, kind: \"pnpm\" };\n    }\n    if (fs.existsSync(path.join(current, \"rush.json\"))) {\n      return { rootDir: current, kind: \"rush\" };\n    }\n    const pkgPath = path.join(current, \"package.json\");\n    if (fs.existsSync(pkgPath)) {\n      try {\n        const pkg = JSON.parse(fs.readFileSync(pkgPath, \"utf8\")) as {\n          workspaces?: unknown;\n        };\n        if (hasWorkspacesField(pkg.workspaces)) {\n          return { rootDir: current, kind: \"workspaces\" };\n        }\n      } catch {\n        /** Malformed or unreadable package.json — ignore and continue upward. */\n      }\n    }\n    const parent = path.dirname(current);\n    if (parent === current) return null;\n    current = parent;\n  }\n  return null;\n}\n\n/**\n * Accepts either an array of globs or a Yarn-style object with a `packages`\n * array. Anything else is treated as not a workspace root.\n */\nfunction hasWorkspacesField(value: unknown): boolean {\n  if (Array.isArray(value)) return true;\n  if (typeof value === \"object\" && value !== null) {\n    const packages = (value as { packages?: unknown }).packages;\n    return Array.isArray(packages);\n  }\n  return false;\n}\n"],"mappings":";;;AAUA,MAAM,YAAY;;;;;;;;;;;AAYlB,SAAgB,eACd,WAAmB,QAAQ,KAAK,EACX;CACrB,IAAI,UAAU,KAAK,QAAQ,SAAS;AACpC,MAAK,IAAI,IAAI,GAAG,IAAI,WAAW,KAAK;AAClC,MAAI,GAAG,WAAW,KAAK,KAAK,SAAS,sBAAsB,CAAC,CAC1D,QAAO;GAAE,SAAS;GAAS,MAAM;GAAQ;AAE3C,MAAI,GAAG,WAAW,KAAK,KAAK,SAAS,YAAY,CAAC,CAChD,QAAO;GAAE,SAAS;GAAS,MAAM;GAAQ;EAE3C,MAAM,UAAU,KAAK,KAAK,SAAS,eAAe;AAClD,MAAI,GAAG,WAAW,QAAQ,CACxB,KAAI;AAIF,OAAI,mBAHQ,KAAK,MAAM,GAAG,aAAa,SAAS,OAAO,CAAC,CAG7B,WAAW,CACpC,QAAO;IAAE,SAAS;IAAS,MAAM;IAAc;UAE3C;EAIV,MAAM,SAAS,KAAK,QAAQ,QAAQ;AACpC,MAAI,WAAW,QAAS,QAAO;AAC/B,YAAU;;AAEZ,QAAO;;;;;;AAOT,SAAS,mBAAmB,OAAyB;AACnD,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO;AACjC,KAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EAC/C,MAAM,WAAY,MAAiC;AACnD,SAAO,MAAM,QAAQ,SAAS;;AAEhC,QAAO"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "detect-monorepo",
+  "version": "1.0.0",
+  "description": "Detect whether a directory sits inside a JS/TS monorepo workspace (pnpm, npm/yarn/bun workspaces, or rush).",
+  "keywords": [
+    "bun",
+    "detect",
+    "monorepo",
+    "npm",
+    "pnpm",
+    "rush",
+    "workspace",
+    "workspaces",
+    "yarn"
+  ],
+  "bugs": {
+    "url": "https://github.com/0x80/detect-monorepo/issues"
+  },
+  "license": "MIT",
+  "author": "Thijs Koerselman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0x80/detect-monorepo.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@codecompose/typescript-config": "^3.2.0",
+    "@types/node": "^25.5.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "oxlint-tsgolint": "^0.20.0",
+    "tsdown": "^0.21.7",
+    "typescript": "6.0.2",
+    "vitest": "^4.1.3"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,cjs}": [
+      "oxfmt",
+      "oxlint -c .oxlintrc.json"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "format": "oxfmt",
+    "lint": "oxlint -c .oxlintrc.json --type-aware",
+    "check-format": "oxfmt --check",
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/detect-monorepo.test.ts

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { detectMonorepo } from "./detect-monorepo";
+
+describe("detectMonorepo", () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "detect-monorepo-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("detects a pnpm workspace via pnpm-workspace.yaml", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "pnpm-workspace.yaml"),
+      "packages:\n  - 'packages/*'\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({ name: "root", version: "1.0.0" }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "pnpm",
+    });
+  });
+
+  it("detects a workspaces array in package.json (npm/yarn/bun)", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({
+        name: "root",
+        version: "1.0.0",
+        workspaces: ["packages/*"],
+      }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "workspaces",
+    });
+  });
+
+  it("detects a workspaces object form in package.json (yarn nohoist)", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({
+        name: "root",
+        version: "1.0.0",
+        workspaces: { packages: ["packages/*"], nohoist: [] },
+      }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "workspaces",
+    });
+  });
+
+  it("detects a rush workspace via rush.json", () => {
+    fs.writeFileSync(path.join(tmpRoot, "rush.json"), "{}");
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "rush",
+    });
+  });
+
+  it("returns null for a standalone package with no workspace markers", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({ name: "standalone", version: "1.0.0" }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toBeNull();
+  });
+
+  it("finds a marker two levels up from the start directory", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "pnpm-workspace.yaml"),
+      "packages:\n  - 'packages/*'\n",
+    );
+    const nested = path.join(tmpRoot, "packages", "api");
+    fs.mkdirSync(nested, { recursive: true });
+    fs.writeFileSync(
+      path.join(nested, "package.json"),
+      JSON.stringify({ name: "api", version: "1.0.0" }),
+    );
+
+    const result = detectMonorepo(nested);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "pnpm",
+    });
+  });
+
+  it("stops searching after MAX_DEPTH (4) levels", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "pnpm-workspace.yaml"),
+      "packages:\n  - 'apps/*/functions/src'\n",
+    );
+    const tooDeep = path.join(tmpRoot, "apps", "firebase", "functions", "src");
+    fs.mkdirSync(tooDeep, { recursive: true });
+
+    const result = detectMonorepo(tooDeep);
+
+    expect(result).toBeNull();
+  });
+
+  it("finds a marker exactly at MAX_DEPTH (3 levels up)", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "pnpm-workspace.yaml"),
+      "packages:\n  - 'apps/*/functions'\n",
+    );
+    const deep = path.join(tmpRoot, "apps", "firebase", "functions");
+    fs.mkdirSync(deep, { recursive: true });
+
+    const result = detectMonorepo(deep);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "pnpm",
+    });
+  });
+
+  it("ignores a malformed package.json and continues upward", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "pnpm-workspace.yaml"),
+      "packages:\n  - 'packages/*'\n",
+    );
+    const nested = path.join(tmpRoot, "packages", "api");
+    fs.mkdirSync(nested, { recursive: true });
+    fs.writeFileSync(path.join(nested, "package.json"), "{ not valid json");
+
+    const result = detectMonorepo(nested);
+
+    expect(result).toEqual({
+      rootDir: tmpRoot,
+      kind: "pnpm",
+    });
+  });
+
+  it("ignores an unexpected workspaces shape", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({
+        name: "root",
+        version: "1.0.0",
+        workspaces: "packages/*",
+      }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toBeNull();
+  });
+
+  it("ignores a workspaces object without a packages array", () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({
+        name: "root",
+        version: "1.0.0",
+        workspaces: { nohoist: [] },
+      }),
+    );
+
+    const result = detectMonorepo(tmpRoot);
+
+    expect(result).toBeNull();
+  });
+
+  it("does not match a package.json without a workspaces field", () => {
+    const nested = path.join(tmpRoot, "subdir");
+    fs.mkdirSync(nested);
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify({ name: "root", version: "1.0.0" }),
+    );
+    fs.writeFileSync(
+      path.join(nested, "package.json"),
+      JSON.stringify({ name: "child", version: "1.0.0" }),
+    );
+
+    const result = detectMonorepo(nested);
+
+    expect(result).toBeNull();
+  });
+});

package/src/detect-monorepo.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type MonorepoInfo = {
+  /** Absolute path to the monorepo workspace root. */
+  rootDir: string;
+  /** Which workspace marker was found. "workspaces" covers npm/yarn/bun. */
+  kind: "pnpm" | "workspaces" | "rush";
+};
+
+const MAX_DEPTH = 4;
+
+/**
+ * Walk upward from `startDir` looking for a monorepo workspace root. Returns
+ * null if none is found within `MAX_DEPTH` levels (startDir itself plus three
+ * parents) or before reaching the filesystem root.
+ *
+ * Supported markers:
+ * - `pnpm-workspace.yaml`
+ * - `package.json` containing a `workspaces` field (npm, yarn, bun)
+ * - `rush.json`
+ */
+export function detectMonorepo(
+  startDir: string = process.cwd(),
+): MonorepoInfo | null {
+  let current = path.resolve(startDir);
+  for (let i = 0; i < MAX_DEPTH; i++) {
+    if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
+      return { rootDir: current, kind: "pnpm" };
+    }
+    if (fs.existsSync(path.join(current, "rush.json"))) {
+      return { rootDir: current, kind: "rush" };
+    }
+    const pkgPath = path.join(current, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
+          workspaces?: unknown;
+        };
+        if (hasWorkspacesField(pkg.workspaces)) {
+          return { rootDir: current, kind: "workspaces" };
+        }
+      } catch {
+        /** Malformed or unreadable package.json — ignore and continue upward. */
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Accepts either an array of globs or a Yarn-style object with a `packages`
+ * array. Anything else is treated as not a workspace root.
+ */
+function hasWorkspacesField(value: unknown): boolean {
+  if (Array.isArray(value)) return true;
+  if (typeof value === "object" && value !== null) {
+    const packages = (value as { packages?: unknown }).packages;
+    return Array.isArray(packages);
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { detectMonorepo } from "./detect-monorepo";
+export type { MonorepoInfo } from "./detect-monorepo";