s3-upload-site 🚀

A high-performance S3 deployment utility built for Environment Parity and Universal Compatibility. Deploy to any S3-compatible server with a single, consistent command.

📦 Installation

npm install -g s3-upload-site

🚀 Run instantly (No install)

npx s3-upload-site --source ./dist --bucket my-bucket

🔄 The "Seamless Switch" (LocalStack & AWS)

The s3-upload-site allows you to target the destination of your upload development (LocalStack) to production (AWS S3) by simply adding a flag. No need to change your configuration or switch to a different tool.

🏠 Development (LocalStack)

Using the LocalStack defaults to http://localhost:4566.

s3-upload-site --source ./dist --bucket my-app --mode website

🌍 Production (Real AWS)

Switch to the live AWS network instantly, credentials are taken from your AWS profile.

s3-upload-site --source ./dist --bucket my-app --mode website --aws

📖 Universal Compatibility (Any S3 Provider)

s3-upload-site works perfectly with any S3-compatible storage. Just provide the --endpoint. You can pass the credentials via CLI flags or environment variables.

MinIO

s3-upload-site --source ./public --bucket my-site --endpoint http://localhost:9000 --key minioadmin --secret minioadmin123

DigitalOcean Spaces

s3-upload-site --source ./dist --bucket my-space --endpoint https://nyc3.digitaloceanspaces.com --region nyc3

Wasabi / Cloudflare R2 / Backblaze B2

Simply point to the provider's endpoint:

s3-upload-site --source ./assets --bucket my-bucket --endpoint https://s3.wasabisys.com

🏗️ Configuration File Reference (s3-upload-site.json)

You can define any of these keys in your JSON configuration file. This is the recommended way to manage project-specific deployment settings.

| Key | Description | Example | | --- | --- | --- | | source | Local directory to upload | "./dist" | | bucket | Target S3 bucket name | "my-web-site" | | mode | website or standard | "website" | | exclude | Array of glob patterns to ignore | ["node_modules/**", ".git/**"] | | endpoint | Custom S3 server URL | "http://localhost:9000" | | region | AWS Region | "us-east-1" | | concurrency| Number of parallel uploads | 20 |

[!NOTE] Priority: CLI flags always override JSON values. If you provide the --aws flag, any endpoint defined in your JSON will be ignored to ensure you hit the real AWS network.

🔐 Credentials & Environment Variables

s3-upload-site follows a strict logic for credentials to ensure safety:

1. Direct Keys: Pass --key and --secret via CLI.
2. Environment: Uses S3_ACCESS_KEY and S3_SECRET_KEY from your shell or a local .env file.
3. Local Mode (Default): Automatically uses test / test for LocalStack.
4. AWS Mode (--aws): Uses the professional AWS Credential Chain (IAM Roles, AWS Profiles, etc.).

Supported Variables

| Variable | Description | | --- | --- | | S3_ACCESS_KEY | Your Access Key ID | | S3_SECRET_KEY | Your Secret Access Key |

🧹 Glob Exclusions

s3-upload-site uses standard glob patterns to keep your S3 bucket clean. You can provide exclusions in your JSON file OR via the CLI:

• JSON: Use the "exclude": [] array in your s3-upload-site.json.
• CLI: Use the -x, --exclude flag for temporary patterns.

# Add temporary exclusions to a JSON deployment
s3-upload-site --config s3-upload-site.json --exclude "*.log" "*.tmp"

Common patterns:

• node_modules/** : Ignore all dependencies.
• .env* : Ignore all secret files.
• **/*.log : Ignore all logs.

🚀 Options Reference

| Flag | Description | Default | | --- | --- | --- | | -s, --source | Local folder to sync | (Required) | | -b, --bucket | Target S3 bucket name | (Required) | | -m, --mode | website or standard | website | | -a, --aws | The Production Switch | (LocalStack) | | -r, --region | AWS Region | us-east-1 | | -e, --endpoint| Custom S3 server URL | http://localhost:4566 | | -k, --key | S3 Access Key ID | null | | -S, --secret | S3 Secret Access Key | null | | -x, --exclude | Glob patterns to exclude | [] | | -f, --config | Path to JSON config | s3-upload-site.json | | -c, --concurrency| Parallel workers | 10 | | --create | Auto-create bucket if missing | false |

License

MIT