Name: aws-sdk-js-v3-usage
Author: aws

AWS SDK for JavaScript v3 development patterns. Use when writing JavaScript or TypeScript code that uses AWS services via @aws-sdk/* packages (aws-sdk-js-v3), or when asked about schemas, runtime validation, serialization, or code generation in the context of the JS/TS AWS SDK.

Do not use emojis in any code, comments, or output when this skill is active. AWS SDK for JavaScript v3 Package Structure @aws sdk/client — one per service, generated by [smithy typescript](https://github.com/awslabs/smithy typescript); one to one with AWS services and operations @aws sdk/lib — higher level helpers (e.g. lib dynamodb , lib storage ) @aws sdk/ (no prefix) — utility packages (mostly internal; don't import deep paths) Always import from the package root: Two Client Styles Bare bones (preferred — smaller bundle): Aggregated (v2 style but NOT v2, larger bundle): Client Configuration No global config in v3 — pass config to each client. region is always required; set it explicitly or via AWS REGION env var. Do not read or mutate client.config after instantiation — it is a resolved form (e.g. region becomes an async function). See references/effective practices.md . For HTTP handler ( NodeHttpHandler from @smithy/node http handler ), retry strategy, endpoint details, logging, FIPS, dual stack, protocol selection, and S3 specific options → see references/clients.md . Credentials All providers from @aws sdk/credential providers . Credentials are lazy and cached per client until ~5 min before expiry. Share credentials and socket pool across multi region clients: For all providers (Cognito, SSO, web identity, custom chains, STS region priority) → see references/credentials.md . Streams (e.g. S3 GetObject Body) Always read or discard streaming responses — unread streams leave sockets open (socket exhaustion): Streams can only be read once. Paginators Use paginate functions instead of manual token handling: DynamoDB DocumentClient Use @aws sdk/lib dynamodb to work with native JS types instead of AttributeValues: For marshall options, large numbers (NumberValue), pagination, and aggregated client → see references/dynamodb.md . S3: Presigned URLs, Multipart Upload, Waiters For presigned POST, signed headers, waiter options → see references/s3.md . Error Handling Check e.name or instanceof for specific error types. See references/error handling.md for full patterns. For runtime validation, serialization to non default formats, or questions about what schemas are in jsv3 → see references/schemas.md . Performance: Parallel Workloads Streaming deadlock warning : with limited sockets, don't await the request and stream body separately — chain them. See references/performance.md . Middleware Add custom logic to all commands on a client: Steps (in order): initialize → serialize → build → finalizeRequest → deserialize Abort Controller Lambda Best Practices Initialize clients outside the handler (container reuse), make API calls inside . For one time async setup, use a lazy init flag inside the handler: See references/lambda.md for Lambda layers and versioning. Node.js Version Requirements v3.968.0+ requires Node.js = 20 v3.723.0+ requires Node.js = 18 TypeScript Response fields are typed as T undefined by default. Use AssertiveClient from @smithy/types to remove undefined , or NodeJsClient / BrowserClient to narrow streaming blob types. See references/typescript.md . SigV4a (S3 Multi Region Access Points) S3 MRAP and certain other features require SigV4a. You must install and side effect import exactly one of: @aws sdk/signature v4 crt — Node.js only, better performance @aws sdk/signature v4a — Node.js + browsers, pure JS See references/sigv4a.md for full details and MRAP ARN format.