Use object storage from Node.js

A Node.js application on Sevalla stores files in an object storage bucket through the bucket’s S3 API: the AWS SDK for JavaScript reads the bucket’s endpoint, name and keys from environment variables, uploads files as they arrive, and hands out presigned URLs to download them. Files in a bucket survive deployments and are shared by every instance, unlike files on an instance’s disk. This guide adds file routes to an Express application. The client code works the same in any Node.js framework.

At a glance

What this guide adds to the Express application:


Services	A private bucket over its S3 API

Environment variables

Variable	Required	Available during	Secret	Value
`S3_ENDPOINT`	Yes	Runtime	No	The bucket’s Endpoint, such as `https://<account-id>.r2.cloudflarestorage.com`
`S3_BUCKET`	Yes	Runtime	No	The bucket’s Bucket name, such as `storefront-media-q8w2e`
`S3_ACCESS_KEY_ID`	Yes	Runtime	Yes	The bucket’s Access key
`S3_SECRET_ACCESS_KEY`	Yes	Runtime	Yes	The bucket’s Secret key

The Express application’s own variables are in its table.

Before you begin

An Express application deployed on Sevalla, as in Deploy Express.
Node.js 20 or later in the application, which the AWS SDK for JavaScript (@aws-sdk/client-s3) needs. The Express guide pins Node.js 24.

Create a bucket

In the sidebar, click Object storage, then click Create object storage. Enter storefront-media as the Name, choose the Location closest to the application, and click Create object storage. See Create a bucket for every field.

Add the bucket details to the application

Copy the values

On the bucket’s Settings tab, copy the Endpoint and Bucket name under Details, and the Access key and Secret key under Access keys.

Add them as environment variables

On the application’s Environment variables tab, click Add environment variables. Add these variables, keep Available during runtime selected, and click Add environment variables:

Variable	Value
`S3_ENDPOINT`	The Endpoint, such as `https://<account-id>.r2.cloudflarestorage.com`
`S3_BUCKET`	The Bucket name, such as `storefront-media-q8w2e`. The display name doesn’t work in S3 requests.
`S3_ACCESS_KEY_ID`	The Access key
`S3_SECRET_ACCESS_KEY`	The Secret key

They apply at the next deployment.

See Connect with the S3 API for what each value is.

Install the AWS SDK

npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner

@aws-sdk/client-s3 sends the S3 requests.
@aws-sdk/lib-storage streams uploads and splits large files into parts.
@aws-sdk/s3-request-presigner creates presigned URLs.

Create the client

Create one client for the whole application:

storage.js

import { S3Client } from "@aws-sdk/client-s3";

export const s3 = new S3Client({
  region: "auto",
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  },
  requestChecksumCalculation: "WHEN_REQUIRED",
  responseChecksumValidation: "WHEN_REQUIRED",
});

export const Bucket = process.env.S3_BUCKET;

Sevalla buckets run on Cloudflare R2, which ignores the region, but the SDK requires one: use auto. The two WHEN_REQUIRED options make the SDK add checksums only to the requests that need them. Without them, it signs the checksum of an empty body (x-amz-checksum-crc32=AAAAAA==) into every presigned upload URL, which doesn’t match the file that’s uploaded with it.

Add routes for files

Add three routes to server.js: one that streams an upload into the bucket, one that lists the files, and one that redirects to a presigned URL for a file:

server.js

import express from "express";
import { GetObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
import { Upload } from "@aws-sdk/lib-storage";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3, Bucket } from "./storage.js";

const app = express();
const port = process.env.PORT || 3000;

// Stream the request body into the bucket as uploads/<name>.
app.put("/files/:name", async (req, res) => {
  await new Upload({
    client: s3,
    params: {
      Bucket,
      Key: `uploads/${req.params.name}`,
      Body: req,
      ContentType: req.headers["content-type"],
    },
  }).done();
  res.status(201).json({ key: `uploads/${req.params.name}` });
});

// List the uploaded files.
app.get("/files", async (req, res) => {
  const { Contents = [] } = await s3.send(
    new ListObjectsV2Command({ Bucket, Prefix: "uploads/" })
  );
  res.json(Contents.map(({ Key, Size }) => ({ key: Key, size: Size })));
});

// Redirect to a link that works for one hour.
app.get("/files/:name", async (req, res) => {
  const url = await getSignedUrl(
    s3,
    new GetObjectCommand({ Bucket, Key: `uploads/${req.params.name}` }),
    { expiresIn: 3600 }
  );
  res.redirect(url);
});

app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

These routes have no authentication: anyone who knows the address can upload files and read them. Check who’s signed in before you upload or sign URLs in a real application.

To try it locally, put the four variables in your shell (for example with export S3_ENDPOINT=...), run npm start, and upload a file with the curl command in Deploy and verify, using http://localhost:3000.

Deploy and verify

Commit and push the changes, package-lock.json included: Ingot installs the new packages from it with npm ci and starts the server from the start script as before. The build doesn’t need the bucket’s variables, only the running server does. With auto-deploy on, the push starts a deployment; otherwise, start one with Deploy now on the application’s Overview tab. When the deployment’s status changes to Deployed:

Upload a PNG file from your computer, such as logo.png in the current folder. Use your application’s domain instead of storefront-x7k2m.sevalla.app:
curl -X PUT --data-binary @logo.png -H "Content-Type: image/png" \ https://storefront-x7k2m.sevalla.app/files/logo.png
The response is {"key":"uploads/logo.png"}.
Open https://storefront-x7k2m.sevalla.app/files/logo.png in a browser. The application redirects to a presigned URL on the bucket’s endpoint, and the image opens.
On the bucket’s Objects tab, open the uploads folder. logo.png is there.

If a request returns 500, read the application’s runtime logs for the S3 error:

Log message	Cause	Fix
`No value provided for input HTTP label: Bucket.`	The `S3_*` variables aren’t set in the running application	Add them on the Environment variables tab with Available during runtime selected, then deploy.
`AccessDenied: Access Denied`	`S3_BUCKET` holds the display name, such as `storefront-media`, instead of the Bucket name: the keys work only for the bucket name	Set `S3_BUCKET` to the Bucket name from the bucket’s Settings tab, then deploy.

For other errors, see the connection troubleshooting table.

Let browsers upload directly

Uploads that pass through the application use its bandwidth and memory. To let the browser send a file straight to the bucket, create a presigned URL for PutObjectCommand on the server and give it to the browser, and add a CORS rule to the bucket for your site’s origin. See Share files with presigned URLs.

Serve files publicly

For files that anyone may read, such as product images, turn on public access on the bucket’s Settings tab and link to the object’s public URL instead of signing one each time. Cloudflare’s CDN caches public files. See Public URLs.

Deploy with the API

This sequence adds the bucket of this guide to the application from Deploy Express through the Sevalla API, so an agent or a script can run it as is. APP_ID is that application, and the changes on this page are pushed to its branch. Each step names the operation, shows the curl command, and gives the matching CLI command and MCP server tool. You need an API key with the Company developer role in the SEVALLA_API_KEY environment variable (the CLI reads the same key from SEVALLA_API_TOKEN), curl and jq. A call that fails returns status and message instead of the resource, and jq -r .id prints null: stop and read the message.

Create the bucket

Create object storage bucket (createObjectStorageV3) creates a private bucket. location is where most reads and writes come from: weur, Western Europe, suits an application in Frankfurt, Germany.

BUCKET_ID=$(curl -s https://api.sevalla.com/v3/object-storage \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "storefront-media", "location": "weur"}' | jq -r .id)

CLI: sevalla object-storage create --name storefront-media --location weur. MCP: sevalla_api_create with createObjectStorageV3 and the same body.

Read the bucket details

Get object storage bucket (getObjectStorageV3) returns the bucket’s endpoint, bucket_name, access_key and secret_key.

BUCKET=$(curl -s https://api.sevalla.com/v3/object-storage/$BUCKET_ID -H "Authorization: Bearer $SEVALLA_API_KEY")

CLI: sevalla object-storage get "$BUCKET_ID" --json. MCP: sevalla_api_read with getObjectStorageV3.

Add the environment variables

Create environment variable (createEnvironmentVariableV3) adds one variable per call. add_var sends each one as available during runtime only, since the build doesn’t need them:

add_var() {
  curl -s https://api.sevalla.com/v3/applications/$APP_ID/env-vars \
    -H "Authorization: Bearer $SEVALLA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg key "$1" --arg value "$2" '{key: $key, value: $value, is_runtime: true, is_buildtime: false}')" | jq -r .key
}
add_var S3_ENDPOINT "$(jq -r .endpoint <<< "$BUCKET")"
add_var S3_BUCKET "$(jq -r .bucket_name <<< "$BUCKET")"
add_var S3_ACCESS_KEY_ID "$(jq -r .access_key <<< "$BUCKET")"
add_var S3_SECRET_ACCESS_KEY "$(jq -r .secret_key <<< "$BUCKET")"

CLI: sevalla apps env-vars create "$APP_ID" --key S3_BUCKET --value "$(jq -r .bucket_name <<< "$BUCKET")", once per variable; the CLI makes each one available during the build too. MCP: set_environment_variables with the four variables in one call, each with runtime true and buildtime false.

Deploy

Trigger deployment (triggerDeploymentV3) builds the latest commit of the branch and rolls it out.

DEPLOYMENT_ID=$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

CLI: sevalla apps deployments trigger "$APP_ID". MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting, then inProgress, then success or failed. The loop polls every 15 seconds for up to 30 minutes and keeps polling through a failed request.

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Check the deployment

List application domains (listApplicationDomainsV3) returns the application’s domain. Upload logo.png from the current folder, list the files, and follow the redirect to the presigned URL:

APP_URL=https://$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/domains \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.data[] | select(.is_primary) | .name')
curl -s -w '\n' -X PUT --data-binary @logo.png -H "Content-Type: image/png" $APP_URL/files/logo.png
curl -s -w '\n' $APP_URL/files
curl -sL -o /dev/null -w '%{http_code} %{content_type}\n' $APP_URL/files/logo.png

The output, with your file’s size in bytes:

{"key":"uploads/logo.png"}
[{"key":"uploads/logo.png","size":70}]
200 image/png

List objects (listObjectStorageObjectsV3) lists the same file from the Sevalla side. CLI: sevalla apps domains list --app-id "$APP_ID" and sevalla object-storage objects list --bucket-id "$BUCKET_ID". MCP: get_application, and sevalla_api_read with listObjectStorageObjectsV3.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Use object storage from Node.js

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install the AWS SDK

Create the client

Add routes for files

Deploy and verify

Let browsers upload directly

Serve files publicly

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create a bucket

​Add the bucket details to the application

​Install the AWS SDK

​Create the client

​Add routes for files

​Deploy and verify

​Let browsers upload directly

​Serve files publicly

​Deploy with the API

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install the AWS SDK

Create the client

Add routes for files

Deploy and verify

Let browsers upload directly

Serve files publicly

Deploy with the API