initial commit for sandboxes pages

_components/Header.tsx

@@ -11,7 +11,7 @@ export default function (
   const hrefIsInCurrentSection = (href: string, currentSection: string) => {
     return href.includes(currentSection) ||
       href === "/services/" &&
-        ["deploy", "subhosting", "services"].includes(
+        ["deploy", "subhosting", "services", "sandboxes"].includes(
           currentSection,
         );
   };

_config.ts

@@ -140,6 +140,7 @@ site.copy("deploy/images");
 site.copy("deploy/classic/images");
 site.copy("deploy/kv/images");
 site.copy("deploy/tutorials/images");
+site.copy("sandboxes/images");
 site.copy("runtime/fundamentals/images");
 site.copy("runtime/getting_started/images");
 site.copy("runtime/reference/images");

_includes/layout.tsx

@@ -10,7 +10,8 @@ export default function Layout(data: Lume.Data) {
     "In-depth documentation, guides, and reference materials for building secure, high-performance JavaScript and TypeScript applications with Deno";
   const isServicesPage = data.url.startsWith("/deploy") ||
     data.url.startsWith("/subhosting") ||
-    data.url.startsWith("/services");
+    data.url.startsWith("/services") ||
+    data.url.startsWith("/sandboxes");
   const hasSubNav = isServicesPage;
 
   return (

_includes/sandbox-example.tsx

@@ -0,0 +1,21 @@
+export const layout = "doc.tsx";
+
+export default function Raw(data: Lume.Data) {
+  return (
+    <>
+      <p className="italic">
+        <a href="https://deno.com/deploy/sandboxes/">Deno Sandboxes</a>{" "}
+        provide a sandboxed environment for evaluating JavaScript code. This is
+        useful for evaluating code that is not trusted or for testing code that
+        is not safe to run in the main runtime.
+      </p>
+
+      {data.children}
+
+      <p className="my-8 block">
+        For more information about Sandboxes, see the{" "}
+        <a href="/sandboxes/">Sandboxes documentation</a>.
+      </p>
+    </>
+  );
+}

deploy/_data.ts

@@ -153,6 +153,10 @@ export const SidebarNav = [
     title: "Deno Deploy",
     href: "/deploy/",
   },
+  {
+    title: "Sandboxes",
+    href: "/sandboxes/",
+  },
   {
     title: "Deploy Classic",
     href: "/deploy/classic/",

deploy/classic/_data.ts

@@ -124,6 +124,10 @@ export const SidebarNav = [
     title: "Deno Deploy",
     href: "/deploy/",
   },
+  {
+    title: "Sandboxes",
+    href: "/sandboxes/",
+  },
   {
     title: "Deploy Classic",
     href: "/deploy/classic/",

examples/_data.ts

@@ -300,6 +300,91 @@ export const sidebar = [
       },
     ],
   },
+  {
+    title: "Sandboxes",
+    items: [
+      {
+        title: "Evaluating JavaScript",
+        href: "/examples/sandboxes_evaluating_javascript/",
+        type: "example",
+      },
+      {
+        title: "Spawn a subprocess",
+        href: "/examples/sandboxes_spawn_subprocess/",
+        type: "example",
+      },
+      {
+        title: "Serve a web framework",
+        href: "/examples/sandboxes_web_framework/",
+        type: "example",
+      },
+      {
+        title: "Privide SSH access to a sandbox",
+        href: "/examples/sandboxes_ssh_access/",
+        type: "example",
+      },
+      {
+        title: "Intereactive JavaScript REPL",
+        href: "/examples/sandboxes_javascript_repl/",
+        type: "example",
+      },
+      {
+        title: "Provide a VSCode instance in a sandbox",
+        href: "/examples/sandboxes_vscode_instance/",
+        type: "example",
+      },
+      {
+        title: "Use template literals with variable interpolation",
+        href: "/examples/sandboxes_template_literals/",
+        type: "example",
+      },
+      {
+        title: "Error handling",
+        href: "/examples/sandboxes_error_handling/",
+        type: "example",
+      },
+      {
+        title: "Error handling with custom error classes",
+        href: "/examples/sandboxes_custom_error_classes/",
+        type: "example",
+      },
+      {
+        title: "Command cancellation",
+        href: "/examples/sandboxes_command_cancellation/",
+        type: "example",
+      },
+      {
+        title: "Access string and binary output",
+        href: "/examples/sandboxes_access_output/",
+        type: "example",
+      },
+      {
+        title: "Set and get environment variables",
+        href: "/examples/sandboxes_environment_variables/",
+        type: "example",
+      },
+      {
+        title: "Stream output to a local file",
+        href: "/examples/sandboxes_stream_output/",
+        type: "example",
+      },
+      {
+        title: "Upload files and directories to a sandbox",
+        href: "/examples/sandboxes_upload_files/",
+        type: "example",
+      },
+      {
+        title: "Control sandbox lifetime",
+        href: "/examples/sandboxes_lifetime_control/",
+        type: "example",
+      },
+      {
+        title: "Configure sandbox memory",
+        href: "/examples/sandboxes_memory/",
+        type: "example",
+      },
+    ],
+  },
   {
     title: "Testing",
     items: [

examples/sandboxes/access_output.md

@@ -0,0 +1,24 @@
+---
+title: "Access string and binary output"
+description: "Learn how to access string and binary output from commands in a sandbox."
+url: /examples/sandboxes_access_output/
+layout: sandbox-example.tsx
+---
+
+You can access string and binary output from commands in a sandbox.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Get both string and binary data
+const result = await sandbox.sh`cat binary-file.png`
+  .stdout("piped");
+console.log("Binary length:", result.stdout!.length);
+console.log("Text length:", result.stdoutText!.length);
+
+// Use the binary data
+import fs from "node:fs";
+fs.writeFileSync("output.png", result.stdout!);
+```

examples/sandboxes/command_cancellation.md

@@ -0,0 +1,30 @@
+---
+title: "Command cancellation"
+description: "Learn how to cancel commands in a sandbox."
+url: /examples/sandboxes_command_cancellation/
+layout: sandbox-example.tsx
+---
+
+You can cancel commands in a sandbox using the `KillController` class.
+
+```ts
+import { KillController, Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Start a long-running command
+const controller = new KillController();
+const cmd = sandbox.sh`sleep 30`.signal(controller.signal);
+const promise = cmd.text();
+
+// Cancel after 2 seconds
+setTimeout(() => {
+  controller.kill(); // Kill the process
+}, 2000);
+
+try {
+  await promise;
+} catch (error) {
+  console.log("Command was cancelled:", error);
+}
+```

examples/sandboxes/custom_error_classes.md

@@ -0,0 +1,23 @@
+---
+title: "Error handling with custom error classes"
+description: "Learn how to handle errors with custom error classes in a sandbox."
+url: /examples/sandboxes_custom_error_classes/
+layout: sandbox-example.tsx
+---
+
+You can handle errors with custom error classes in a sandbox.
+
+```ts
+import { Sandbox, SandboxCommandError } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+try {
+  await sandbox.sh`exit 42`;
+} catch (error) {
+  if (error instanceof SandboxCommandError) {
+    console.log("Exit code:", error.code); // → 42
+    console.log("Error message:", error.message);
+  }
+}
+```

examples/sandboxes/environment_variables.md

@@ -0,0 +1,23 @@
+---
+title: "Set and get environment variables"
+description: "Learn how to set and get environment variables in a sandbox."
+url: /examples/sandboxes_environment_variables/
+layout: sandbox-example.tsx
+---
+
+You can use the `sandbox.env.set()` method to set environment variables in a
+sandbox.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Set environment variables
+await sandbox.env.set("API_KEY", "secret-key-123");
+await sandbox.env.set("NODE_ENV", "production");
+
+// Use them in a script
+const apiKey = await sandbox.sh`echo $API_KEY`.text();
+console.log("API_KEY:", apiKey.trim());
+```

examples/sandboxes/error_handling.md

@@ -0,0 +1,27 @@
+---
+title: "Error handling"
+description: "Learn how to handle errors in a sandbox."
+url: /examples/sandboxes_error_handling/
+layout: sandbox-example.tsx
+---
+
+Commands in a sandbox throw by default on non-zero exit. You can use the
+`noThrow()` method to handle errors manually.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Commands throw by default on non-zero exit
+try {
+  await sandbox.sh`exit 1`;
+} catch (error) {
+  console.log("Command failed:", error);
+}
+
+// Use noThrow() to handle errors manually
+const result = await sandbox.sh`exit 1`.noThrow();
+console.log("Exit code:", result.status.code); // → 1
+console.log("Success:", result.status.success); // → false
+```

examples/sandboxes/evaluating_javascript.md

@@ -0,0 +1,21 @@
+---
+title: "Evaluating JavaScript"
+description: "Learn how to evaluate JavaScript code in a sandbox."
+url: /examples/sandboxes_evaluating_javascript/
+layout: sandbox-example.tsx
+---
+
+You can evaluate JavaScript code in a sandbox using the `eval` function.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+const result = await sandbox.eval(`
+  const a = 1;
+  const b = 2;
+  a + b;
+`);
+console.log("result:", result);
+```

examples/sandboxes/javascript_repl.md

@@ -0,0 +1,27 @@
+---
+title: "Intereactive JavaScript REPL"
+description: "Learn how to provide an interactive JavaScript REPL in a sandbox."
+url: /examples/sandboxes_javascript_repl/
+layout: sandbox-example.tsx
+---
+
+The `sandbox.repl()` method can be used to provide an interactive JavaScript
+REPL in a sandbox.
+
+This example shows how to start a JavaScript REPL in a sandbox and execute code
+interactively.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Start a JavaScript REPL
+const repl = await sandbox.repl();
+
+// Execute code interactively, maintaining state
+await repl.eval("const x = 42;");
+await repl.eval("const y = 8;");
+const result = await repl.eval("x + y");
+console.log("result:", result); // 50
+```