DEV Community

Oleksandr
Oleksandr

Posted on

Reviving a Dead Plugin: How I Bring Back To Life the serverless-s3-sync plugin

#aws #serverless #webdev #opensource

If you've been using the Serverless Framework to deploy static assets to S3, you've probably used serverless-s3-sync. It was the go-to plugin for syncing local directories to S3 buckets. Simple config, works after sls deploy, done.

Then, on January 1, 2026, the original author archived the repository. No more updates, no more security fixes. The most worrying thing - no more security fixes.

So I forked it, cleaned it up, and published it as serverless-s3-sync-v2.

Original Plugin Had a Problem

The original serverless-s3-sync worked, but its dependency tree was a historical artifact:

// Original dependencies (k1LoW/serverless-s3-sync)
{
  "@auth0/s3": "^1.0.0",
  "bluebird": "^3.5.1",
  "mime": "^2.4.0",
  "minimatch": "^3.0.4"
}
Enter fullscreen mode Exit fullscreen mode

@auth0/s3 is itself a fork of the andrewrk/node-s3-client library, which hasn't been maintained for years. It's built on top of AWS SDK v2, which is also deprecated and has end-of-support on September 8, 2025. It handled the entire upload logic: directory scanning, MD5 diffing, multipart uploads, and the actual putObject calls.

bluebird was a Promise polyfill that made sense in 2015, when native Promises were slow or unreliable in Node.js. In 2026, it's pure dead weight.

The result: to sync a folder to S3, you were pulling in an unmaintained S3 client library that wrapped an unmaintained Promise library that wrapped an outdated AWS SDK. Four layers of abandoned code between you and a simple PutObject API call.

The Fork: What Changed

  1. Replaced @auth0/s3 + bluebird with direct AWS SDK v3

The most significant change. Instead of delegating to a middleware library, the fork talks directly to @aws-sdk/client-s3:

// Before (via @auth0/s3 abstraction)
const client = s3.createClient({ s3Options: awsOptions });
const uploader = client.uploadDir({ localDir, s3Params: { Bucket, Prefix } });

// After (direct AWS SDK v3)
const { S3Client, PutObjectCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
const client = new S3Client(awsOptions);
await client.send(new PutObjectCommand({ Bucket, Key, Body, ContentType, ...params }));
Enter fullscreen mode Exit fullscreen mode

AWS SDK v3 is modular — you import only what you need. No more pulling in the entire SDK.

  1. Rewrote sync logic with native async/await

bluebird is gone. All async operations use native Promise and async/await. The Node.js built-in crypto module handles MD5 hashing for ETag comparison:

const crypto = require('crypto');

function computeMD5(filePath) {
  return new Promise((resolve, reject) => {
    const hash = crypto.createHash('md5');
    const stream = fs.createReadStream(filePath);
    stream.on('data', chunk => hash.update(chunk));
    stream.on('end', () => resolve(hash.digest('hex')));
    stream.on('error', reject);
  });
}
Enter fullscreen mode Exit fullscreen mode
  1. Node.js ≥ 20 requirement

The fork sets "node": ">=20" in engines. This enables native test runner (node --test), native fetch, and all modern async primitives without polyfills.

  1. Updated mime and minimatch

mime upgraded from v2 to v4 (ESM-aware, smaller, maintained)
minimatch upgraded from v3 to v10

  1. Added ESLint with standard config

The original repo lacks adding a consistent code style enforced via a linter. For linting JavaScript code, I added standard. For now, the standard hasn't been updated for 2 years, and I hope it will be brought back to life soon.

  1. Native Node.js test runner

Tests migrated from no tests to node --test, removing the need for a separate test framework dependency. A lot of unit tests were added to confirm the stability of the code.

Migration from the Original

If you're already using serverless-s3-sync, migration is two steps:

  1. Swap the package: 
npm uninstall serverless-s3-sync
npm install --save serverless-s3-sync-v2
Enter fullscreen mode Exit fullscreen mode
  1. Update serverless.yml: 
plugins:
  - serverless-s3-sync-v2  # was: serverless-s3-sync
Enter fullscreen mode Exit fullscreen mode

Your existing custom.s3Sync configuration stays exactly the same. All options are preserved:

  • bucketName / bucketNameKey
  • bucketPrefix
  • localDir
  • deleteRemoved
  • acl
  • params (per-file headers like CacheControl)
  • bucketTags
  • enabled (conditional sync rules)
  • --nos3sync CLI flag
  • Custom hooks
  • Offline mode via serverless-s3-local

Links

npm: serverless-s3-sync-v2
GitHub: AlexHladin/serverless-s3-sync
Original (archived): k1LoW/serverless-s3-sync

If this saved you from a supply chain dependency nightmare, give it a ⭐ on GitHub. PRs and issues welcome.

Top comments (0)