aws-sdk-js-v3: Modular AWS SDK for JavaScript and What It Costs You

What aws-sdk-js-v3 replaces, and who ends up maintaining it

Version 2 of the AWS SDK for JavaScript shipped every AWS service in one package. That was convenient for a project that calls three services and painful for a Lambda that calls one, because the unused service code still had to be resolved and, in bundled targets, still had to be shipped. The v3 rewrite answers that with a separate package per service. The README describes the result plainly: the SDK is "split up across multiple packages", and the 2.x version "contained support for every service".

The audience is therefore narrower than "anyone using AWS from JavaScript". It is teams whose deployment target punishes bundle size or cold-start time: Lambda functions, browser clients, react-native apps. It is also teams that want TypeScript types generated from the service models rather than hand-maintained, since first-class TypeScript support is one of the features the README lists alongside the middleware stack. If you run a long-lived Node.js server where a few extra megabytes of node_modules never leave the box, the modular split buys you less, though the typed clients still buy you something.

One package per service, one command per call

The architecture visible in the repository is a monorepo of workspaces. The root package.json declares workspaces over clients/*, lib/*, packages/*, packages-internal/* and private/*, which is why a single install pulls a client package plus the shared runtime packages it depends on. Each client package exposes a Client class and a Command class per operation. You construct the client once with configuration such as a region, then send command objects through it.

The README shows both call styles. The modular style imports DynamoDBClient and ListTablesCommand and calls client.send(command). The non-modular style imports DynamoDB and calls client.listTables({}) directly. The README's own note on this is the trade-off: using the non-modular interface "will increase the bundle size as compared to using modular interface" when tree shaking is in play. So the ergonomic v2-shaped API is still available, and it costs you the thing v3 was built to give you.

Credentials, retries and endpoint resolution sit in the shared packages rather than in each client, which is what makes per-service packages practical. The middleware stack is the extension point: request handling runs through composable steps, and the README points to a separate write-up on the middleware stack for the details. The repository also carries codegen/ and clients/ at the top level, and the Makefile has a test-codegen target that copies from private/aws-protocoltests-restjson, which tells you the clients are generated rather than written by hand.

Installing aws-sdk-js-v3 and listing DynamoDB tables

The README walks through a DynamoDB project using yarn and assumes Node.js and yarn are already installed. Add the client package for the one service you need:

yarn add @aws-sdk/client-dynamodb

The README is explicit that this updates yarn.lock or package-lock.json and that you "should" commit the lock file with your code to avoid potential breaking changes. That instruction matters more here than in a typical library, because the SDK publishes on a fast cadence and the client packages are versioned together.

Create index.js and send a command. The README's example constructs the client with a region and awaits the response:

const { DynamoDBClient, ListTablesCommand } = require("@aws-sdk/client-dynamodb");

(async () => {
  const client = new DynamoDBClient({ region: "us-west-2" });
  const command = new ListTablesCommand({});
  try {
    const results = await client.send(command);
    console.log(results.TableNames.join("\n"));
  } catch (err) {
    console.error(err);
  }
})();

Run it with node index.js against an account where you have credentials and DynamoDB permissions. You should see table names printed one per line, or the error object if the call fails. The region in the snippet is us-west-2; change it to match your tables. If you prefer the v2 shape, the README shows the same call as new DynamoDB({ region: "us-west-2" }) followed by client.listTables({}), with the bundle-size caveat noted above.

For react-native targets the README requires three polyfills, imported before the client:

import "react-native-get-random-values";
import "react-native-url-polyfill/auto";
import "web-streams-polyfill/dist/polyfill";

import { DynamoDB } from "@aws-sdk/client-dynamodb";

It also says Metro's Package Exports Support must be enabled, and links to the Metro and React Native documentation for that. Nothing in the README covers bundler configuration beyond that pointer.

Where aws-sdk-js-v3 gets awkward

The modular split moves the cost from runtime to dependency management. A service-per-package layout means a project touching a dozen services has a dozen client packages to keep in step, and the README's advice to commit the lock file is the mitigation, not a fix. The root package.json is private and marked UNLICENSED, so the repository itself is not the thing you install; the published client packages are, and they carry the Apache-2.0 licence the repository declares.

The version cadence is the second friction point. The recent releases run v3.1138.0, v3.1137.0 and v3.1136.0 across three consecutive working days in September 2026, and the last push to main was on 2026-09-23. A patch stream that dense means lock files drift quickly and CI that resolves latest on every build will see constant churn. Pin, and read release notes before bumping.

The third is the non-modular escape hatch. It is genuinely useful when porting v2 code, but the README warns it increases bundle size under tree shaking, so reaching for it to avoid rewriting call sites quietly gives back the main benefit. Treat it as a migration tool, not a destination.

Finally, the README's Known Issues section names functionality that requires the AWS Common Runtime, and the Makefile carries a signature-v4-crt package with its own vitest config. If your workload depends on that path, the CRT dependency is a separate build concern from the pure-JavaScript clients, and the README does not document a fallback.

aws-sdk-js-v3 against the v2 monolith

The real alternative is not another vendor's SDK. It is the version this one replaces. The aws-sdk v2 package gives you every service behind one import and one version number. You install it once, you never think about which client package you need, and you cannot accidentally hold two versions of a service client in the same tree.

v3 inverts each of those. You install only what you call, and in exchange you own the dependency list. Tree shaking works because each client is a separate module graph, which is exactly what v2 could not offer. TypeScript definitions ship with the generated clients rather than being maintained separately, which is the second structural difference.

The README does not present v2 as a parallel option. It points anyone starting fresh at the aws-sdk-js-notes-app sample and anyone migrating at a self-guided workshop that builds a note-taking application in v2 and then walks through the move to v3 step by step. That framing is the honest one: v3 is the forward path, and the escape hatch exists so the move can be incremental rather than a flag day.

Release cadence, upgrade cost and the Apache-2.0 terms

The repository publishes client packages on a near-daily cadence, and each release is versioned at the package level. Upgrading is therefore a lock-file operation, not a code change, most of the time. The cost shows up in two places: reviewing release notes for the services you actually use, and re-running your own tests after a bump, because a patch release in a generated client can change a type signature even when the wire protocol is unchanged.

On licensing, the repository declares Apache-2.0 and the root package.json is private and marked UNLICENSED, which is normal for a monorepo whose publishable artefacts are the workspaces. Apache-2.0 permits commercial and closed-source use and includes a patent grant; it also requires that you retain the licence and notice files for the packages you redistribute. If you vendor or bundle a client into something you ship, check that your build preserves those notices. That is the shape of the obligation, not legal advice for your situation.

The README also states Node.js, ECMAScript and TypeScript version support policies as separate sections, and a stability policy for modular packages. If your runtime or compiler sits at the edge of a supported range, read those sections before upgrading rather than after.

Editorial conclusion

Adopt aws-sdk-js-v3 for new Node.js, browser or react-native projects that touch more than a couple of AWS services, and for any codebase already carrying the v2 monolith into a bundle. Stay on v2 only if a dependency pins it and you have not yet run the migration workshop, since the README treats v2 as the thing you migrate away from rather than a parallel track. Before you commit, verify three things in your own tree: that your lock file is committed, that every package you add resolves to a v3 client rather than the v2 aws-sdk, and that any react-native target has the polyfills the README lists. The release cadence is the practical constraint, not the API surface.

Frequently asked questions

Official sources

1. aws/aws-sdk-js-v3 on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases