Neon

Neon branchable object storage via the S3-compatible API. neon dev / neon env pull inject the AWS_* env vars; path-style addressing is required.

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { neon } from "files-sdk/neon";

const files = new Files({
  adapter: neon({
    bucket: "images",
    // endpoint defaults to AWS_ENDPOINT_URL_S3
    // region defaults to AWS_REGION (then NEON_STORAGE_REGION, then us-east-1)
    // accessKeyId / secretAccessKey resolve from the AWS credential chain
    // (the AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY Neon injects)
  }),
});

Neon branchable object storage via its S3-compatible API. A thin wrapper around the S3 adapter - errors relabelled, path-style addressing on by default. Declare a bucket in your neon.ts policy (preview.buckets), then run neon dev (or neon env pull) to mint a branch credential and inject the standard AWS_* variables. Inside a deployed Neon Function the same variables are present, so the adapter works from env alone:

const files = new Files({ adapter: neon({ bucket: "images" }) });

await files.upload("avatars/abc.png", file, { contentType: "image/png" });
const url = await files.url("avatars/abc.png", { expiresIn: 300 });

Path-style addressing is required: Neon’s wildcard TLS certificate covers a single subdomain level (*.storage.<suffix>), which the branch id occupies, so the bucket name must travel in the request path. The adapter always uses path-style addressing.

Options

PropType

bucketstring

Neon object-storage bucket name. The adapter scopes all operations to it.

Typestring

endpoint?string

The branch's S3-compatible endpoint URL. Falls back to `AWS_ENDPOINT_URL_S3` — the variable `neon dev` / `neon env pull` inject for the linked branch. Required if that env var isn't set.

Typestring

region?string

SigV4 region used for signing. Falls back to `AWS_REGION`, then `NEON_STORAGE_REGION` (Neon injects the region under both names), then defaults to `"us-east-1"`. Neon normalizes the region server-side and does not use it for routing, but the signature requires *some* value.

Typestring

accessKeyId?string

Static access key ID. Skip to use the AWS credential chain, which reads the `AWS_ACCESS_KEY_ID` that `neon dev` / `neon env pull` inject for the branch credential.

Typestring

secretAccessKey?string

Static secret access key. Skip to use the AWS credential chain, which reads the `AWS_SECRET_ACCESS_KEY` Neon injects for the branch credential.

Typestring

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — appropriate for a bucket fronted by a CDN or custom domain. When unset, `url()` falls back to a presigned `GetObject` URL (default expiry: 1 hour).

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour).

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅