Upload files to S3 with automatic cleanup. Useful in tests and scripts that need to stage a file in S3 temporarily and remove it when done.
Each function uploads a file to S3 and returns a TempFileOnS3 object
containing the resolved key, the ETag from S3, and an async cleanup() function
that deletes the object when called.
If no key is provided, one is generated automatically: for file uploads the
original filename is preserved with a UUID suffix (e.g. report_3a9f...c1.pdf),
and for string uploads a plain UUID is used with an optional extension.
npm install s3-tempimport { tempFileOnS3 } from 's3-temp'
const { cleanup, key, eTag } = await tempFileOnS3({
localPath: '/tmp/report.pdf',
bucket: 'my-bucket',
})
try {
// Work with `key` and optionally `eTag`.
} finally {
await cleanup()
}Provide a key to use a fixed path instead of a generated one:
const key = 'uploads/report.pdf'
const { cleanup, eTag } = await tempFileOnS3({
localPath: '/tmp/report.pdf',
bucket: 'my-bucket',
key,
})
try {
// Work with `key` and optionally `eTag`.
} finally {
await cleanup()
}import { tempFileOnS3FromString } from 's3-temp'
const { cleanup, key, eTag } = await tempFileOnS3FromString({
contents: '<html>hello</html>',
bucket: 'my-bucket',
extension: '.html',
})
try {
// Work with `key` and optionally eTag.
} finally {
await cleanup()
}| Option | Type | Required | Description |
|---|---|---|---|
localPath |
string |
yes | Path to the local file to upload |
bucket |
string |
yes | S3 bucket name |
key |
string |
no | S3 object key (auto-generated if omitted) |
encoding |
BufferEncoding |
no | File encoding passed to fs.readFile |
verbose |
boolean |
no | Log upload/removal to stderr |
| Option | Type | Required | Description |
|---|---|---|---|
contents |
string |
yes | String content to upload |
bucket |
string |
yes | S3 bucket name |
key |
string |
no | S3 object key (auto-generated if omitted) |
extension |
string |
no | Extension appended to generated key (e.g. '.json') |
verbose |
boolean |
no | Log upload/removal to stderr |
| Property | Type | Description |
|---|---|---|
key |
string |
The S3 object key |
eTag |
string |
ETag returned by S3 on upload |
cleanup() |
() => Promise<void> |
Deletes the object from S3 |
The integration tests upload real objects to S3. Copy .env.example to .env
and fill in the values before running tests.
| Variable | Description |
|---|---|
AWS_PROFILE |
AWS credentials profile to use for local development |
AWS_REGION |
AWS region (e.g. us-east-1) |
TEST_BUCKET |
S3 bucket to use for integration tests |
For local development, set AWS_PROFILE and AWS_REGION to use a credentials
profile from ~/.aws/credentials. In CI, omit these and set AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY directly.
npm test