Configure S3-compatible access for Next.js

Summary

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.

Representative Queries

• Configure S3-compatible access for Next.js
• Where can I host Configure S3-compatible access built with Next.js?
• I need exact S3 endpoint, credentials, operation requirements and an upload/download verification.

Infrastructure Requirements

• Compute: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.
• S3-compatible object storage: Buckets are S3-compatible with issued credentials; PutObject and GetObject are verified by canary. Other S3 operations are not verified.

Workload

Configure S3-compatible access.

Prerequisites

1. 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.
2. A bucket created with ample bucket create and its credentials from ample bucket credentials .
3. An Ample account token with servers:write and buckets:read.

Workflow Steps

1. Create the bucket
   Create it once and keep the issued credentials out of the repository. Command: ample bucket create --name
2. Configure the client with path-style addressing
   Use @aws-sdk/client-s3 inside a dynamic route handler with forcePathStyle: true; virtual-host addressing is not verified.
3. Deploy with the credentials as encrypted env
   Pass the five S3_* variables with --env; they are stored encrypted and reused on redeploys.
   Command: ample deploy . --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.
   Command: ample logs --kind build

Examples

Next.js bucket canary

Write and read an object with the injected credentials.
Source reference: tests/deploy-canaries/next-bucket-uploads.

Success Checks

• Object write and read succeed:
  HTTP GET path: /api/storage
  Expect: s3=ok

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• PutObject and GetObject with path-style addressing are verified; multipart upload, listing, presigned URLs and lifecycle rules are not verified.
• Bucket credentials are passed as encrypted environment variables; the catalog never creates the bucket for you (use ample bucket create).
• Storage is allocation-priced per bucket quota and capped by the account plan; the estimate below covers compute only.

Cost Estimate

• Currency: USD
• Monthly Amount: 5.0
• Note: Compute only. Buckets are allocation-priced per quota and capped by the plan; see ample usage.

Evidence Summary

1. Kind: Canary Run
   Summary: Next.js route handler using @aws-sdk/client-s3 with injected bucket credentials: PutObject then GetObject returned s3=ok at request time.
   Observed At: 2026-09-20T01:13:26Z
2. Kind: Canary Run
   Summary: ample bucket create issued credentials; PutObject and GetObject succeeded through the public S3 endpoint; publish exposed the object through the CDN host with an ETag; unpublish and delete cleaned up.
   Observed At: 2026-09-20T01:13:26Z

Formats

• HTML: Link
• Markdown: Link
• JSON: Link