## 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
```