fix: don't fail install when running npm install in an example workspace (#687)

examples/basic-host/README.md

@@ -12,8 +12,16 @@ This basic host can also be used to test MCP Apps during local development.
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run start
 # Open http://localhost:8080
 ```

examples/basic-server-preact/README.md

@@ -57,8 +57,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/basic-server-react/README.md

@@ -59,8 +59,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/basic-server-solid/README.md

@@ -57,8 +57,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/basic-server-svelte/README.md

@@ -57,8 +57,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/basic-server-vanillajs/README.md

@@ -58,8 +58,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/basic-server-vue/README.md

@@ -57,8 +57,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/budget-allocator-server/README.md

@@ -60,9 +60,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/cohort-heatmap-server/README.md

@@ -60,9 +60,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/customer-segmentation-server/README.md

@@ -61,9 +61,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/integration-server/README.md

@@ -17,8 +17,16 @@ This example demonstrates all App SDK communication APIs and is used by the E2E
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/lazy-auth-server/README.md

@@ -16,8 +16,16 @@ The embedded OAuth authorization server is a deliberately minimal mock (HS256 JW
 
 ## Getting Started
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm start
 # → MCP endpoint at http://localhost:3097/mcp
 ```

examples/map-server/README.md

@@ -52,9 +52,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/scenario-modeler-server/README.md

@@ -60,9 +60,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/shadertoy-server/README.md

@@ -59,9 +59,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/sheet-music-server/README.md

@@ -55,9 +55,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/system-monitor-server/README.md

@@ -59,9 +59,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/threejs-server/README.md

@@ -52,9 +52,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

examples/transcript-server/README.md

@@ -61,7 +61,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ### Installation
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
 ```
 

examples/video-resource-server/README.md

@@ -45,8 +45,16 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Quick Start
 
+The examples are npm workspaces that share the SDK built at the repository root, so install from there first:
+
 ```bash
+# from the repository root
 npm install
+```
+
+Then run this example from its directory:
+
+```bash
 npm run dev
 ```
 

examples/wiki-explorer-server/README.md

@@ -58,9 +58,10 @@ To test local modifications, use this configuration (replace `~/code/ext-apps` w
 
 ## Running
 
-1. Install dependencies:
+1. Install dependencies from the repository root (the examples are npm workspaces that share the SDK built there):
 
    ```bash
+   # from the repository root
    npm install
    ```
 

package.json

@@ -64,7 +64,7 @@
     "examples:start": "NODE_ENV=development npm run build && bun examples/run-all.ts start",
     "examples:dev": "NODE_ENV=development bun examples/run-all.ts dev",
     "watch": "nodemon --watch src --ext ts,tsx --exec 'bun build.bun.ts'",
-    "prepare": "npm run build && husky",
+    "prepare": "node scripts/prepare.mjs",
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
     "generate:screenshots": "npm run build:all && docker run --rm -e EXAMPLE -e GENERATE_SCREENSHOTS=1 -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.57.0-noble sh -c 'apt-get update -qq && apt-get install -qq -y python3-venv curl > /dev/null && curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH=\"$HOME/.local/bin:$PATH\" && npm i -g bun && npm ci && npx playwright test tests/e2e/generate-grid-screenshots.spec.ts'",

scripts/prepare.mjs

@@ -0,0 +1,55 @@
+/**
+ * `prepare` lifecycle script.
+ *
+ * npm runs `prepare` on every `npm install`, including when someone installs a
+ * single workspace example via `npm install` inside `examples/<name>`. That flow
+ * installs only that workspace's dependencies and does NOT install the root
+ * package's devDependencies (ts-to-zod, bun, tsx, esbuild, husky, ...), yet npm
+ * still runs this root `prepare`. Running the build there used to fail with a
+ * cryptic `ERR_MODULE_NOT_FOUND: ts-to-zod`.
+ * See https://github.com/modelcontextprotocol/ext-apps/issues/687.
+ *
+ * We detect a missing build toolchain and skip the build with a helpful message
+ * instead of crashing. Registry consumers are unaffected: `prepare` does not run
+ * for published packages and `dist/` ships in the tarball. Git installs still
+ * build, because npm installs a git dependency's devDependencies before running
+ * its `prepare`.
+ */
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+// Root-only devDependencies that `npm run build` needs. If any is missing we are
+// in a partial install (e.g. a workspace-child install) that cannot build.
+const REQUIRED_TOOLING = ["ts-to-zod", "bun", "tsx"];
+
+const missing = REQUIRED_TOOLING.filter((pkg) => {
+  try {
+    require.resolve(`${pkg}/package.json`);
+    return false;
+  } catch {
+    return true;
+  }
+});
+
+if (missing.length > 0) {
+  console.log(
+    `[prepare] Skipping SDK build: missing build tooling (${missing.join(", ")}).`,
+  );
+  console.log(
+    "[prepare] This is expected when installing a single example. To build the " +
+      "SDK and run the examples, run `npm install` from the repository root.",
+  );
+  process.exit(0);
+}
+
+execSync("npm run build", { stdio: "inherit" });
+
+// Install git hooks (husky). Best-effort: never fail the install if husky cannot
+// run (e.g. when installing outside a git checkout).
+try {
+  execSync("husky", { stdio: "inherit" });
+} catch {
+  // husky is optional for local development; ignore failures.
+}