feat: update all doc examples to use ESM instead of CJS

Convert sandbox code in permissions, module-loading, filesystem,
virtual-filesystem, child-processes, plugin-systems, ai-agent-code-exec,
dev-servers, and node runtime docs from require/module.exports to
import/export with .mjs filePath.

Author: NathanFlurry

README.md

@@ -64,9 +64,9 @@ const { text } = await generateText({
   stopWhen: stepCountIs(5),
   tools: {
     execute: tool({
-      description: "Run JavaScript in a secure sandbox. Assign the result to module.exports to return data.",
+      description: "Run JavaScript in a secure sandbox. Use export to return data.",
       inputSchema: z.object({ code: z.string() }),
-      execute: async ({ code }) => runtime.run(code),
+      execute: async ({ code }) => runtime.run(code, "/entry.mjs"),
     }),
   },
 });

docs/features/child-processes.mdx

@@ -68,7 +68,7 @@ const runtime = new NodeRuntime({
 
 try {
   const result = await runtime.exec(`
-    const { spawnSync } = require("node:child_process");
+    import { spawnSync } from "node:child_process";
 
     const child = spawnSync("node", ["--version"], {
       encoding: "utf8",
@@ -81,7 +81,7 @@ try {
     if (child.status !== 0 || !output.startsWith("v")) {
       throw new Error("Unexpected child process exit code: " + child.status);
     }
-  `);
+  `, { filePath: "/entry.mjs" });
 
   if (result.code !== 0) {
     throw new Error(`Unexpected execution result: ${JSON.stringify(result)}`);

docs/features/filesystem.mdx

@@ -32,10 +32,10 @@ const runtime = new NodeRuntime({
 
 try {
   const result = await runtime.exec(`
-    const fs = require("node:fs");
+    import fs from "node:fs";
     fs.mkdirSync("/workspace", { recursive: true });
     fs.writeFileSync("/workspace/hello.txt", "hello from the sandbox");
-  `);
+  `, { filePath: "/entry.mjs" });
 
   if (result.code !== 0) {
     throw new Error(`Unexpected execution result: ${JSON.stringify(result)}`);

docs/features/module-loading.mdx

@@ -9,7 +9,7 @@ icon: "cubes"
   Runnable example for module resolution and loading.
 </Card>
 
-Sandboxed code can `require()` and `import` modules through secure-exec's module resolution system.
+Sandboxed code can `import` and `require()` modules through secure-exec's module resolution system.
 
 ## Runnable example
 
@@ -36,10 +36,10 @@ const runtime = new NodeRuntime({
 try {
 	const result = await runtime.run<{ version: string }>(
 		`
-    const typescript = require("/root/node_modules/typescript/lib/typescript.js");
-    module.exports = { version: typescript.version };
+    import typescript from "/root/node_modules/typescript/lib/typescript.js";
+    export const version = typescript.version;
   `,
-		"/app/example.js",
+		"/app/example.mjs",
 	);
 
 	if (result.code !== 0 || typeof result.exports?.version !== "string") {
@@ -66,7 +66,7 @@ Node runtime executions expose a read-only dependency overlay at `/app/node_modu
 
 ```ts
 // Inside the sandbox, this resolves from the host's node_modules
-const lodash = require("lodash");
+import lodash from "lodash";
 ```
 
 Key constraints:

docs/features/permissions.mdx

@@ -37,7 +37,7 @@ const result = await runtime.run<{
 	blocked: boolean;
 }>(
 	`
-  const fs = require("node:fs");
+  import fs from "node:fs";
 
   fs.mkdirSync("/workspace", { recursive: true });
   fs.writeFileSync("/workspace/message.txt", "hello from permissions");
@@ -49,11 +49,10 @@ const result = await runtime.run<{
     blocked = error && error.code === "EACCES";
   }
 
-  module.exports = {
-    message: fs.readFileSync("/workspace/message.txt", "utf8"),
-    blocked,
-  };
+  export const message = fs.readFileSync("/workspace/message.txt", "utf8");
+  export { blocked };
 `,
+	"/entry.mjs",
 );
 
 console.log(

docs/features/virtual-filesystem.mdx

@@ -148,8 +148,9 @@ class ReadOnlyMapFS implements VirtualFileSystem {
 ```ts
 const fs = new ReadOnlyMapFS({
   "/config.json": JSON.stringify({ greeting: "hello" }),
-  "/src/index.js": `
-    const config = JSON.parse(require("fs").readFileSync("/config.json", "utf8"));
+  "/src/index.mjs": `
+    import { readFileSync } from "node:fs";
+    const config = JSON.parse(readFileSync("/config.json", "utf8"));
     console.log(config.greeting);
   `,
 });
@@ -163,9 +164,10 @@ const runtime = new NodeRuntime({
 });
 
 const result = await runtime.exec(`
-  const config = JSON.parse(require("fs").readFileSync("/config.json", "utf8"));
+  import { readFileSync } from "node:fs";
+  const config = JSON.parse(readFileSync("/config.json", "utf8"));
   console.log(config.greeting);
-`);
+`, { filePath: "/entry.mjs" });
 
 // Output captured via onStdio callback — see Output Capture docs
 runtime.dispose();

docs/runtimes/node.mdx

@@ -246,8 +246,8 @@ const runtime = new NodeRuntime({
 });
 
 const execution = await runtime.run<{ answer: number }>(
-  "module.exports = require('./dist/index.js');",
-  "/root/entry.js",
+  "export { default as answer } from './dist/index.js';",
+  "/root/entry.mjs",
 );
 
 console.log(execution.exports); // { answer: 42 }

docs/use-cases/ai-agent-code-exec.mdx

@@ -12,7 +12,7 @@ Give your agent a code-execution tool with explicit CPU and memory limits. The a
 
 ## Run generated JavaScript
 
-The agent writes JavaScript, assigns a return value to `module.exports`, and gets it back.
+The agent writes JavaScript, uses `export` to return values, and the host gets them back.
 
 ```ts JavaScript Execution
 import { generateText, stepCountIs, tool } from "ai";
@@ -38,9 +38,9 @@ const { text } = await generateText({
   stopWhen: stepCountIs(5),
   tools: {
     execute: tool({
-      description: "Run JavaScript in a secure sandbox. Assign the result to module.exports to return data.",
+      description: "Run JavaScript in a secure sandbox. Use export to return data.",
       inputSchema: z.object({ code: z.string() }),
-      execute: async ({ code }) => runtime.run(code),
+      execute: async ({ code }) => runtime.run(code, "/entry.mjs"),
     }),
   },
 });
@@ -87,7 +87,7 @@ const ts = createTypeScriptTools({
 const { text } = await generateText({
   model: anthropic("claude-sonnet-4-6"),
   prompt:
-    "Write TypeScript that calculates the first 20 fibonacci numbers. Assign the result to module.exports.",
+    "Write TypeScript that calculates the first 20 fibonacci numbers. Use export to return the result.",
   stopWhen: stepCountIs(5),
   tools: {
     execute_typescript: tool({
@@ -99,7 +99,7 @@ const { text } = await generateText({
           sourceText: code,
           filePath: "/root/generated.ts",
           compilerOptions: {
-            module: "commonjs",
+            module: "esnext",
             target: "es2022",
           },
         });
@@ -116,7 +116,7 @@ const { text } = await generateText({
           sourceText: code,
           filePath: "/root/generated.ts",
           compilerOptions: {
-            module: "commonjs",
+            module: "esnext",
             target: "es2022",
           },
         });
@@ -131,7 +131,7 @@ const { text } = await generateText({
 
         const execution = await runtime.run<Record<string, unknown>>(
           compiled.outputText,
-          "/root/generated.js"
+          "/root/generated.mjs"
         );
 
         if (execution.code !== 0) {

docs/use-cases/dev-servers.mdx

@@ -38,27 +38,23 @@ const runtime = new NodeRuntime({
 });
 
 const execPromise = runtime.exec(`
-  (async () => {
-    const { Hono } = require("hono");
-    const { serve } = require("@hono/node-server");
-
-    const app = new Hono();
-    app.get("/", (c) => c.text("hello from sandboxed hono"));
-    app.get("/health", (c) => c.json({ ok: true }));
-
-    serve({
-      fetch: app.fetch,
-      port: ${port},
-      hostname: "${host}",
-    });
+  import { Hono } from "hono";
+  import { serve } from "@hono/node-server";
+
+  const app = new Hono();
+  app.get("/", (c) => c.text("hello from sandboxed hono"));
+  app.get("/health", (c) => c.json({ ok: true }));
 
-    console.log("server:listening:${port}");
-    await new Promise(() => {});
-  })().catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
+  serve({
+    fetch: app.fetch,
+    port: ${port},
+    hostname: "${host}",
   });
+
+  console.log("server:listening:${port}");
+  await new Promise(() => {});
 `, {
+  filePath: "/app/server.mjs",
   onStdio: (event) => logs.push(`[${event.channel}] ${event.message}`),
 });
 

docs/use-cases/plugin-systems.mdx

@@ -26,22 +26,21 @@ import {
 const filesystem = createInMemoryFileSystem();
 await filesystem.mkdir("/plugins");
 await filesystem.writeFile(
-  "/plugins/title-case.js",
+  "/plugins/title-case.mjs",
   `
-    module.exports = {
-      manifest: {
-        name: "title-case",
-        version: "1.0.0",
-      },
-      transform(input, options = {}) {
-        const words = String(input)
-          .split(/\\s+/)
-          .filter(Boolean)
-          .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase());
-
-        return (options.prefix ?? "") + words.join(" ");
-      },
+    export const manifest = {
+      name: "title-case",
+      version: "1.0.0",
     };
+
+    export function transform(input, options = {}) {
+      const words = String(input)
+        .split(/\\s+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase());
+
+      return (options.prefix ?? "") + words.join(" ");
+    }
   `
 );
 
@@ -62,16 +61,14 @@ const result = await runtime.run<{
   manifest: { name: string; version: string };
   output: string;
 }>(`
-  const plugin = require("/plugins/title-case.js");
-
-  module.exports = {
-    manifest: plugin.manifest,
-    output: plugin.transform(
-      ${JSON.stringify(input)},
-      ${JSON.stringify(options)}
-    ),
-  };
-`, "/root/run-plugin.js");
+  import { manifest, transform } from "/plugins/title-case.mjs";
+
+  export { manifest };
+  export const output = transform(
+    ${JSON.stringify(input)},
+    ${JSON.stringify(options)}
+  );
+`, "/root/run-plugin.mjs");
 
 console.log(result.exports?.manifest.name); // "title-case"
 console.log(result.exports?.output); // "Plugin says: Hello From Plugin Land"