s3-spa-upload

library2.1.5jsnpmunverified

CLI and programmatic tool for uploading SPAs to AWS S3 with correct Content-Type and Cache-Control headers. Version 2.1.5 fixes content-type detection and includes S3 prefix support, concurrency control, optional delete of stale files, and custom cache-control mapping via glob patterns. It uploads index.html last to ensure atomic deployments. No file change detection or multipart upload. Stable, use it for small to medium SPAs with simple deployment needs.

devops

npm install s3-spa-upload

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · S3-SPA-UPLOAD

s3-spa-upload

devopsjavascriptv2.1.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (s3SpaUpload)

✓ import s3SpaUpload from 's3-spa-upload'

✗ const s3SpaUpload = require('s3-spa-upload').default

ESM default export. CJS require works without .default only in v2+ due to mixed module format.

S3SpaUploadOptions

✓ import type { S3SpaUploadOptions } from 's3-spa-upload'

✗ import { S3SpaUploadOptions } from 's3-spa-upload'

Type-only import for TypeScript users.

CacheControlMapping

✓ import type { CacheControlMapping } from 's3-spa-upload'

Type exported for custom mapping objects.

Uploads a local dist directory to an S3 bucket with custom cache-control, deletion of stale files, and concurrency control.

import s3SpaUpload from 's3-spa-upload'; const options = { delete: true, prefix: 'app', cacheControlMapping: { 'index.html': 'no-cache', '*.js': 'public,max-age=31536000,immutable' }, concurrency: 50, awsCredentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', sessionToken: process.env.AWS_SESSION_TOKEN } }; s3SpaUpload('./dist', 'my-bucket', options) .then(() => console.log('Upload complete')) .catch(err => console.error('Upload failed:', err));

Debug

Known issues

gotcha--delete option requires s3:ListBucket and s3:DeleteObject permissions

fix

Add those permissions to your IAM policy or omit the --delete flag.

affects: >=1.0.0

gotchaNo file change detection; all files are re-uploaded on each run

fix

Use a separate tool like s3sync for incremental uploads if bandwidth is a concern.

affects: >=1.0.0

gotchaLarge files are not split into multipart uploads; upload may fail for files > 5GB

fix

Upgrade to v2+ or limit file sizes.

affects: <2.0.0

deprecatedaws-sdk v2 is used; AWS SDK v3 is recommended

fix

Consider migrating to @aws-sdk/client-s3 if you need SDK v3 features.

affects: <3.0.0

Errors

Common errors & fixes

TypeError: s3SpaUpload is not a function

Using CJS require with v2 import

fix

Use 'const s3SpaUpload = require("s3-spa-upload")' (no .default) for CommonJS.

Error: Missing required parameter: Body

File read failed or path is incorrect

fix

Ensure the dist directory exists and contains files.

AccessDenied: Access Denied

Missing S3 write permissions

fix

Add s3:PutObject to your IAM policy.

Upgrade

Version history

2.1.5latest on npm

Audit

Dependencies

aws-sdkrequiredS3 operations (PutObject, ListObjects, DeleteObjects)

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ottokruse/s3-spa-upload ↗

packages3-spa-upload ↗

homepagehttps://github.com/ottokruse/s3-spa-upload#readme ↗