Registry / aws / s3-folder-upload

s3-folder-upload

JSON →
library2.3.5jsnpmunverified

s3-folder-upload is a Node.js utility designed for efficiently uploading local static file directories to Amazon S3 buckets. The package is currently stable at version `2.3.5`, with minor releases deployed on an as-needed basis to introduce new features, fix bugs, or update dependencies, rather than adhering to a strict release schedule. It utilizes the official AWS SDK internally, ensuring robust and reliable integration with S3 services. Key differentiators include its flexible credential management, allowing configuration via environment variables, direct parameters, or AWS IAM role credentials, and providing granular control over S3 object properties such as `ACL`, `CacheControl`, and `Expires` headers, which can be applied globally or per file. The module also supports optional CloudFront invalidation, streamlining cache updates after deployments. Additionally, it offers a command-line interface (CLI) for quick and programmatic deployments, making it well-suited for integration into CI/CD pipelines or for local development workflows managing static assets.

npm install s3-folder-upload
INSTALL
IMPORT
SIG · S3-FOLDER-UPLOAD
S
s3-folder-upload
awsjavascriptv2.3.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

s3FolderUpload
import s3FolderUpload from 's3-folder-upload'
import { s3FolderUpload } from 's3-folder-upload'
The library uses a default export. Attempting to use a named import (e.g., `import { s3FolderUpload } from 's3-folder-upload'`) will result in an undefined symbol.
s3FolderUpload
const s3FolderUpload = require('s3-folder-upload')
const { s3FolderUpload } = require('s3-folder-upload')
For CommonJS environments, `require` returns the default export directly. While supported, ES Modules are generally recommended for new Node.js projects.

Demonstrates uploading a local directory to S3 with explicit credentials and optional configurations, including CloudFront invalidation. Creates dummy files for easy testing.

import s3FolderUpload from 's3-folder-upload'; import path from 'path'; import fs from 'fs'; // Ensure environment variables are set or provide credentials directly const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID'; const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY'; const AWS_REGION = process.env.AWS_REGION ?? 'us-east-1'; const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME ?? 'YOUR_S3_BUCKET_NAME'; const directoryName = path.resolve('./public'); // Example: your static files are in a 'public' folder // Create a dummy 'public' directory and file for demonstration if it doesn't exist if (!fs.existsSync(directoryName)) { fs.mkdirSync(directoryName, { recursive: true }); fs.writeFileSync(path.join(directoryName, 'index.html'), '<h1>Hello S3!</h1>'); fs.writeFileSync(path.join(directoryName, 'style.css'), 'body { background-color: lightblue; }'); console.log(`Created dummy static files in '${directoryName}'.`); } const credentials = { accessKeyId: AWS_ACCESS_KEY_ID, secretAccessKey: AWS_SECRET_ACCESS_KEY, region: AWS_REGION, bucket: AWS_BUCKET_NAME }; const options = { useFoldersForFileTypes: false, // Upload files directly to the root of the bucket/uploadFolder uploadFolder: 'app-statics', // Optional: Upload into a subfolder within the S3 bucket ACL: 'public-read', // Default ACL for uploaded objects CacheControl: 'public, max-age=31536000' // Default Cache-Control }; // Optional CloudFront invalidation settings const invalidation = { awsDistributionId: process.env.CLOUDFRONT_DISTRIBUTION_ID ?? 'YOUR_CLOUDFRONT_DISTRIBUTION_ID', awsInvalidationPath: '/*', // Invalidate all paths }; async function uploadStatics() { if (!AWS_BUCKET_NAME || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY) { console.error('AWS credentials and bucket name must be provided via environment variables or directly.'); process.exit(1); } try { console.log(`Starting S3 upload from ${directoryName} to bucket ${credentials.bucket}...`); await s3FolderUpload(directoryName, credentials, options, invalidation); console.log('S3 upload and optional CloudFront invalidation completed successfully!'); } catch (error) { console.error('Error during S3 upload:', error); process.exit(1); } } uploadStatics();
s3-folder-upload --version
Debug
Known issues
breakingSince `v2.1.0`, the main `s3FolderUpload` function was refactored to return a Promise. Any existing code relying on synchronous execution or callback patterns from previous versions will break and needs to be updated to use `await` or `.then()`.
fix
Update all programmatic calls to `s3FolderUpload` to handle the returned Promise, for example by using `await s3FolderUpload(...)` within an `async` function or `.then().catch()`.
affects: >=2.1.0
gotchaBy default, the `useFoldersForFileTypes` option is `true`. This causes files to be uploaded into S3 subdirectories based on their file extensions (e.g., `js/main.js`, `css/style.css`). If you desire a flat directory structure in your S3 bucket, you must explicitly set `useFoldersForFileTypes: false` in your options.
fix
Pass `{ useFoldersForFileTypes: false }` in the options object to upload files directly to the specified `uploadFolder` or bucket root.
affects: >=2.0.0
gotchaThe library offers multiple ways to provide AWS credentials (environment variables, direct parameters, IAM roles). The precedence can be confusing. Explicit parameters override environment variables, and `useIAMRoleCredentials: true` overrides all others.
fix
Establish a clear credential loading strategy. For consistent behavior, consider using IAM role credentials on EC2/ECS or providing credentials exclusively via environment variables for CI/CD, avoiding mixing methods unless strictly necessary.
affects: >=2.0.0
gotchaCloudFront invalidation is an optional feature and requires a separate `invalidation` object as the fourth parameter. It is not automatically performed after an upload unless explicitly configured.
fix
To enable CloudFront invalidation, ensure you pass an `invalidation` object with `awsDistributionId` and `awsInvalidationPath` to the `s3FolderUpload` function. Without it, CloudFront caches will not be updated.
affects: >=2.0.0
Errors
Common errors & fixes
Missing credentials in config
AWS SDK was unable to find valid credentials for authentication with S3 based on environment variables, configuration files, or direct parameters.
fix
Ensure `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables are correctly set, or pass `accessKeyId`, `secretAccessKey`, `region`, and `bucket` directly in the credentials object, or enable `useIAMRoleCredentials: true` on an EC2 instance with an appropriate IAM role.
Error: Access Denied
The provided AWS credentials lack the necessary permissions (e.g., `s3:PutObject`, `s3:ListBucket`) to perform operations on the target S3 bucket.
fix
Verify that your IAM user or role has a policy attached that grants `s3:PutObject`, `s3:PutObjectAcl`, `s3:ListBucket`, and `s3:GetBucketLocation` permissions for the specified bucket and path. Also check the bucket's own policy.
Error: ENOENT: no such file or directory, stat '<directoryName>'
The `directoryName` path provided to `s3FolderUpload` does not exist on the local filesystem where the script is being executed.
fix
Double-check that the `directoryName` variable correctly points to an existing local folder containing the static files you wish to upload. Use `path.resolve()` for absolute paths.
The specified bucket does not exist
The S3 bucket name specified in the credentials or configuration does not exist in the specified AWS region, or it is misspelled.
fix
Confirm the `bucket` name in your credentials object or environment variables is correct and that the bucket exists in the AWS `region` you've configured.
Upgrade
Version history
2.3.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources