AWS SDK v2 or v3 - which one should you use?

If you have been using Javascript and AWS SDK in the last year you might have noticed this message while browing in their documentation:

Well, in fact AWS SDK version 3 has been publicly available for a year now that, so I took the opportunity of a brand new shiny project to start using it.

Was it a good idea?

I can't tell you yet, we are still writing the first few lines of code, but adopting it comes with some hiccups.

What is the difference?

Among the others the main interesting changes and features are

• Modular architecture: a separate package for each service. No need to pull in the entire sdk to just use s3!
• First class Typescript support.
• Middleware: instead of attaching listeners to a request to manipulate it and control the lifecycle of a call, it is now possible to use a middleware stack where Each middleware in the stack calls the next middleware after making any changes to the request object, improving readability and debugging experience.
• Individual Configuration: there is no longer a global configuration managed by the SDK. Configuration must be passed to each service client that is instantiated.

I really suggest checking out the repo and especially the Upgrading section for more details.

Here just a couple of simple examples

With version 2 you would import stuff and do calls like this - assuming you stay far away from callbacks and prer to use async await:

const AWS = require("aws-sdk");
const s3Client = new AWS.S3({});

// yes you can also do. 
// const S3 = require('aws-sdk/clients/s3');
// const s3Client = new S3({})

await s3Client.createBucket(params).promise();

With version 3 you just npm install and require the individual service/package

const { S3 } = require("@aws-sdk/client-s3");
const s3Client = new S3({});
await s3Client.createBucket(params);

As you can see not a big deal of a difference, but much nicer.

On the other side, although I still find it nicer and more readable and reusable, the Command approach require quite some changes to the code and takes time to get use to it.

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"; 
const client = new S3Client(config);
const input = {
    Bucket: 'abc', // your bucket name,
    Key: 'abc.txt' // path to the object you're looking for
}
const command = new GetObjectCommand(input);
const response = await client.send(command);

while in version 2

const aws = require('aws-sdk');
const s3 = new aws.S3(); 

var getParams = {
    Bucket: 'abc', // your bucket name,
    Key: 'abc.txt' // path to the object you're looking for
}

const response = await s3.getObject(getParams).promise()

Anyway, we started our project like that, taking slightly longer for every little thing, just to get used to the new documentation, which also has a complete different format, but we were quite happy, until we realised that some Middy middleware was still relying on old version of SDK and we started wondering if that would have worked at all.
After some searches we found out surprisingly that the Lambda Runtime does not come with aws-sdk v3 preinstalled, but v2.

how? why?! is that a problem?

Yes, according to these lambda examples:

AWS SDK for JavaScript v2, and not v3, is installed in the default Lambda Node.js environment. The examples linked here demonstrate how to bundle the required AWS SDK for JavaScript v3 modules with the example code.

Does it mean that we need to bundle services from both versions then?
Not really, because you can always exclude the aws-sdk from your bundle, since it is, well, already available in Lambda runtime:

In CDK for example you can skip aws-sdk from bundling like this:

    bundling: {
                minify: true,
                externalModules: [
                    'aws-sdk', // Use the 'aws-sdk' available in the Lambda runtime
                ],
            },

So,

• when you use v2 you dont have to bundle your lambda with it, because it is already in the runtime you can just bundle your code and have smaller packages.

• if you use v3 you have modular architecture so you are not pulling in the entire aws, but just the code that you need, so bundle is smaller. Here you can read an interesting article from AWS Team describing how they halved the publish size of the modular SDK.

Of course we can bundle only the tiny packages we use and import from version 3, and if our middlewares use something from v2 they will grab it from the runtime.
But does then all this make sense?

So should you use v3 or not?

Well... that depends. First, if you are writing code interacting with AWS which will run on your machine, or on docker, and not on lambda, it definitely makes sense to use v3.
But even on lambda... apparently the code from the 2 versions can coexist ( although ugly and confusing for developers) so it is not a problem, and according to some, you should always anyway bundle aws-sdk because of slight differences in what you think you are using (the latest stable version and the version installed on the Lambda runtime. (for example at the time of writing this Latest release for v2 is 2.1045.0 while the installed version in the runtime is 2.1001.0 - that's 44 minor versions with improvements and bug fixes!!)

Furthermore, other middlewares and packages will soon upgrade, so this problem will become less common, and in the meantime you can still take advantage of typescript, modular architecture and drop that freaking .promise() thing.

So, honestly, I would not migrate a running project, but if you are starting from scratch a new project, in my opinion it make sense to start using v3 - which is not something beta or cutting edge - if you go to github or the official docs you see everywhere suggestions to use V3 since it has been publicly available for a year now.

If you want to know more about pros and cons of v3 and read other opinions I really suggest this article

Hope it helps