# 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](/content/guides/next-js/object-client/index.html)  
- **Markdown**: [Link](/content/guides/next-js/object-client.md)  
- **JSON**: [Link](https://api.ample.computer/v1/catalog/recipes/page%3Aguides%3Anext-js%3Aobject-client)