README.md

AWS SDK V3 Nest

AWS SDK Javascript V3 dynamic module for NestJS

Quick Start

Let's build a S3 client and inject it into the nest app.

npm install aws-sdk-v3-nest @aws-sdk/client-s3

1. Register the module with a S3 Client, in app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { AwsSdkModule } from 'aws-sdk-v3-nest';
import { S3Client } from '@aws-sdk/client-s3';

@Module({
  imports: [
    // register S3 client
    AwsSdkModule.register({
      client: new S3Client({
        region: 'us-west-2',
      }),
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

2. use the S3 client in app.controller.ts

import { ListBucketsCommand, S3Client } from '@aws-sdk/client-s3';
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
import { InjectAws } from 'aws-sdk-v3-nest';

@Controller()
export class AppController {
  constructor(
    private readonly appService: AppService,
    // inject the client
    @InjectAws(S3Client) private readonly s3: S3Client 
  ) {}
  @Get()
  async helloAws() {
    const listCommand = new ListBucketsCommand({});
    const res = await this.s3.send(listCommand);
    return res;
  }
}

3. done!

Installation

• Add aws-sdk-v3-nest to your project

   npm install aws-sdk-v3-nest

• Make sure at least one AWS SDK for JavaScript V3 is in your project. Please skip this step if you already have it installed

  npm install @aws-sdk/client-s3

Add Environment Variables

Ensure the following environment variables are present in your project. These variables are critical for authentication and communication with AWS services.

Security Note: Treat these keys as sensitive information. Do not commit them to public repositories and ensure they are securely stored and accessed.

Setting Up: Typically, these variables are placed in a .env file in your project's root directory or configured directly in your deployment platform's environment settings.

AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key

Register a Client

You can register any AWS SDK client you want. As long as it's a AWS SDK V3 client

A good example: S3Client

import { S3Client } from '@aws-sdk/client-s3';
import { AwsSdkModule } from 'aws-sdk-v3-nest';

// ... your code ...

AwsSdkModule.register({
  client: new S3Client({
    region: 'us-west-2',
  }),
});

Async Register

The library provides an async useFactory that allows you to add more logics before setting up the client instance.

import { S3Client, ListBucketsCommand } from '@aws-sdk/client-s3';
import { AwsSdkModule } from 'aws-sdk-v3-nest';

//... your code ...

AwsSdkModule.registerAsync({
  clientType: S3Client,
  useFactory: async () => {
    const s3 = new S3Client({
      region: 'us-west-2',
    });

    try {
      const listCommand = new ListBucketsCommand({});
      const res = await s3.send(listCommand);
      console.log('Connected to S3');
    } catch (e) {
      console.log('Unable to connect to S3', e);
    }

    return s3;
  },
});

Use @InjectAws(Client)

With a registered S3 client, you can now inject the instance to your service and controller.

Make sure the Client is the type you registered in module.

/** Use S3 client in AppController */
import { ListBucketsCommand, S3Client } from '@aws-sdk/client-s3';
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
import { InjectAws } from 'aws-sdk-v3-nest';

@Controller()
export class AppController {
  constructor(
    private readonly appService: AppService,
    @InjectAws(S3Client) private readonly s3: S3Client,
  ) {}
  @Get()
  async helloAws() {
    const listCommand = new ListBucketsCommand({});
    const res = await this.s3.send(listCommand);
    return res;
  }
}

Multiple Injection/Instances

To add more instances is easy, just register more! If you have same type of clients, please use the key attribute as the identifier.

Example for multiple S3 client instances

Register the S3 Client with a unique key

AwsSdkModule.register({
  // register the S3 Client with key `US-WEST-2-CLIENT`
  key: 'US-WEST-2-CLIENT',
  client: new S3Client({
    region: 'us-west-2',
  }),
}),
AwsSdkModule.register({
  // register the S3 Client with key `US-EAST-1-CLIENT`
  key: 'US-EAST-1-CLIENT',
  client: new S3Client({
    region: 'us-east-1',
  }),
}),

Inject and refer clients by @InjectAws(Client, key)

@InjectAws(S3Client, "US-WEST-2-CLIENT") private readonly s3west2: S3Client,
@InjectAws(S3Client, "US-EAST-1-CLIENT") private readonly s3east1: S3Client,

Global Module

By default, a client is only available at where it is registered. You have an option to make it global, isGlobal: true

AwsSdkModule.register({
  isGlobal: true,
  client: new S3Client({
    region: 'us-west-2',
  }),
});

Get client token

If you need a client key for testing purpose. Please pass the AWS SDK V3 client and key to getClientToken

getClientToken(S3Client, key = "")

Credit

Inspired by: nest-aws-sdk