+
+## Prerequisites
+
+- A Depot account with an organization
+- Node.js installed locally
+- [Depot CLI](/docs/cli/installation) installed
+
+## Setup
+
+This tutorial uses code from our [example repository](https://github.com/depot/examples/tree/main/build-api). Clone it to follow along:
+
+```shell
+git clone https://github.com/depot/examples.git
+cd examples/build-api
+```
+
+The example repository contains the following Node.js examples under (`nodejs/`):
+
+- [`list-projects.js`](https://github.com/depot/examples/blob/main/build-api/nodejs/src/list-projects.js) - List all projects
+- [`create-project.js`](https://github.com/depot/examples/blob/main/build-api/nodejs/src/create-project.js) - Create a new project
+- [`delete-project.js`](https://github.com/depot/examples/blob/main/build-api/nodejs/src/delete-project.js) - Delete a project
+- [`create-build.js`](https://github.com/depot/examples/blob/main/build-api/nodejs/src/create-build.js) - Build image with options (load/save/push)
+
+To get started, install Node.js dependencies:
+
+```bash
+cd nodejs
+npm install
+```
+
+## Step 1: Create an organization token
+
+1. Navigate to your organization settings in the Depot dashboard
+2. Scroll to **API Tokens** section
+3. Enter a description (e.g., `test-token`) and click **Create token**
+4. Copy the token and save it securely (you won't see it again)
+
+Set the token as an environment variable:
+
+```shell
+export DEPOT_TOKEN=
+```
+
+## Step 2: Install Depot CLI
+
+Install via curl:
+
+```shell
+curl -L https://depot.dev/install-cli.sh | sh
+```
+
+Or via Homebrew (macOS):
+
+```shell
+brew install depot/tap/depot
+```
+
+## Step 3: Create a project
+
+Projects in Depot provide isolated builder infrastructure and cache storage. We recommend creating a separate project for each customer organization to maximize cache effectiveness and prevent cache poisoning.
+
+To create a project, use the `ProjectService.createProject` method with your organization token:
+
+```javascript
+const {depot} = require('@depot/sdk-node')
+
+const headers = {
+ Authorization: `Bearer ${process.env.DEPOT_TOKEN}`,
+}
+
+const result = await depot.core.v1.ProjectService.createProject(
+ {
+ name: 'my-project',
+ regionId: 'us-east-1',
+ cachePolicy: {keepBytes: 50 * 1024 * 1024 * 1024, keepDays: 14}, // 50GB, 14 days
+ },
+ {headers},
+)
+
+console.log(result.project.projectId)
+```
+
+Try it with the example: `node nodejs/src/create-project.js my-project`
+
+Save the `projectId` from the output, you'll need it for builds.
+
+Example output:
+
+```text
+_Project {
+ projectId: 'krt0wtn195',
+ organizationId: '3d1h48dqlh',
+ name: 'my-project',
+ regionId: 'us-east-1',
+ createdAt: Timestamp { seconds: 1708021346n, nanos: 83000000 },
+ cachePolicy: _CachePolicy { keepBytes: 53687091200n, keepDays: 14 }
+}
+```
+
+## Step 4: Build a Docker image
+
+To build an image, first register a build with the Build API using `BuildService.createBuild`. This returns a build ID and one-time build token that you pass to the Depot CLI:
+
+```javascript
+const {depot} = require('@depot/sdk-node')
+const {exec} = require('child_process')
+
+const headers = {
+ Authorization: `Bearer ${process.env.DEPOT_TOKEN}`,
+}
+
+// Register the build
+const result = await depot.build.v1.BuildService.createBuild({projectId: ''}, {headers})
+
+// Execute build with Depot CLI
+exec(
+ 'depot build --load .',
+ {
+ env: {
+ DEPOT_PROJECT_ID: '',
+ DEPOT_BUILD_ID: result.buildId,
+ DEPOT_TOKEN: result.buildToken,
+ },
+ },
+ (error, stdout, stderr) => {
+ if (error) {
+ console.error(`Error: ${error}`)
+ return
+ }
+ console.log(stdout)
+ },
+)
+```
+
+Try it with the example: `node nodejs/src/create-build.js `
+
+The `--load` flag downloads the built image to your local Docker daemon.
+
+## Step 5: Run the container
+
+List your local Docker images:
+
+```shell
+docker image ls
+```
+
+Run the built container:
+
+```shell
+docker run
+```
+
+You should see "Hello World" output from the Node.js application.
+
+## Step 6: Save to a registry
+
+### Push to Depot Registry
+
+Instead of loading locally with `--load`, you can save the image to Depot Registry using the `--save` flag:
+
+```javascript
+exec('depot build --save .', {
+ env: {
+ DEPOT_PROJECT_ID: '',
+ DEPOT_BUILD_ID: result.buildId,
+ DEPOT_TOKEN: result.buildToken,
+ },
+})
+```
+
+Try it: `node nodejs/src/create-build.js save`
+
+The build output shows how to pull or push the saved image:
+
+```text
+Saved target:
+ To pull: depot pull --project
+ To push: depot push --project --tag
+```
+
+### Push to external registries
+
+To push directly to Docker Hub, GHCR, ECR, or other registries during the build, use the `--push` flag with `--tag`:
+
+```javascript
+exec('depot build --push --tag docker.io/myuser/myapp:latest .', {
+ env: {
+ DEPOT_PROJECT_ID: '',
+ DEPOT_BUILD_ID: result.buildId,
+ DEPOT_TOKEN: result.buildToken,
+ },
+})
+```
+
+First authenticate with `docker login`, then pushing to other registries simply requires setting the proper image name:
+
+```shell
+# Docker Hub
+node nodejs/src/create-build.js push docker.io/myuser/myapp:latest
+
+# GitHub Container Registry
+node nodejs/src/create-build.js push ghcr.io/myorg/myapp:latest
+
+# AWS ECR
+node nodejs/src/create-build.js push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
+```
+
+