# Configure S3-compatible access for Next.js

Configure S3-compatible access for a Next.js app on Ample. Create a bucket with `ample bucket create`, pass its endpoint, region, bucket name and keys as encrypted environment variables, and use @aws-sdk/client-s3 inside a dynamic route handler with forcePathStyle: true. The app writes and reads objects through the S3-compatible endpoint; the bucket stays private.

## What it runs on

- [Compute](/content/discover/primitive/compute/index.html)  
  Apps run in isolated x86_64 Firecracker microVMs; sizes are the priced VM sizes.

- [S3-compatible object storage](/content/discover/primitive/s3-compatible-object-storage/index.html)  
  Buckets speak the S3 API with SigV4 credentials Ample Computer issues; `ample bucket upload-url` returns a presigned upload URL. PutObject and GetObject are checked by canary.

## You need

- An S3 client in the app (@aws-sdk/client-s3 inside a dynamic route handler with forcePathStyle: true) reading S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY

- A bucket created with `ample bucket create <name>` and its credentials from `ample bucket credentials <name>`

- An Ample account token with servers:write and buckets:read

## Exact tested configuration

- build    
npm run build --if-present
- install  
npm install
- runtime   
node
- sizes-1vcpu-1gb
- start    
npm run start
- template  
node-22

## Steps

1. **Create the bucket.** Create it once and keep the issued credentials out of the repository.

```
   $ ample bucket create --name <bucket-name>
   ```

2. **Configure the client with path-style addressing.** Use @aws-sdk/client-s3 inside a dynamic route handler with forcePathStyle: true (path-style addressing).

3. **Deploy with the credentials as encrypted env.** Pass the five S3_* variables with --env; they are stored encrypted and reused on redeploys.

```
   $ ample deploy . --name <app-name> --public --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...
   ```

4. **Test through the app.** Expose a route (/api/storage) that writes then reads an object and reports s3=ok.

5. **Verify.** Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

```
   $ ample logs <deployment_id> --kind build
   ```

## How it was checked

✓ object write and read succeed · http get/api/storage → “s3=ok”

## Evidence

1. November 5, 2026 · canary run
   Next.js route handler using @aws-sdk/client-s3 with injected bucket credentials: PutObject then GetObject returned s3=ok at request time.

2. November 5, 2026 · canary run
   ample bucket create issued credentials; PutObject and GetObject succeeded through the public S3 endpoint; publish exposed the object at its public URL with an ETag; unpublish and delete cleaned up.

## Tested examples

- **Next.js bucket canary.** Write and read an object with the injected credentials.

## What it doesn’t cover

- Verified on the node-22 template at s-1vcpu-1gb.
- Buckets speak the standard S3 API (PutObject and GetObject with path-style addressing are checked by the fixtures); `ample bucket upload-url` returns presigned upload URLs.
- Bucket credentials are passed as encrypted environment variables; the catalog never creates the bucket for you (use `ample bucket create`).
- Storage counts what you store, within your plan's allowance; the estimate below covers compute only.
