The NodeBoot AWS Starter package provides seamless integration with AWS services using the AWS SDK v3. It enables dependency injection and auto-configuration for AWS clients such as DynamoDB, S3, Secrets Manager, SNS, and SQS.
- First install the AWS Starter package for NodeBoot:
npm install @nodeboot/starter-aws- To enable AWS services in a NodeBoot application, use the
@EnableAwsdecorator:
import "reflect-metadata";
import {NodeBoot, NodeBootApp, NodeBootApplication, NodeBootAppView} from "@nodeboot/core";
import {ExpressServer} from "@nodeboot/express-server";
import {EnableComponentScan} from "@nodeboot/aot";
import {EnableAws} from "@nodeboot/starter-aws";
@EnableAws()
@EnableComponentScan()
@NodeBootApplication()
export class FactsServiceApp implements NodeBootApp {
start(): Promise<NodeBootAppView> {
return NodeBoot.run(ExpressServer);
}
}By doing this, the NodeBoot autoconfiguration mechanism will setup AWS clients depending on configurations under the "integrations.aws" config path. Clients are optional, so if configuration for a client is provided, the system will require the installation of the AWS client package in order to setup the integration. If integration is well configured, the client is created and added to the Dependency Injection container for later injection into services.
AWS SDK configuration can be done through environment variables, configuration files, or explicitly in the application " app-config.yaml" file.
The recommended way to provide configurations in Node-Boot is to use the application config file "app-config.yaml" where you can provide all sort of configs, including environment variables.
integrations:
aws:
credentials:
accessKeyId: "${AWS_ACCESS_KEY_ID}"
secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"Set the following environment variables to configure AWS SDK authentication:
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_SESSION_TOKEN=your-session-token # (Optional)
export AWS_REGION=us-east-1AWS credentials can be stored in ~/.aws/credentials and the region in ~/.aws/config.
~/.aws/credentials:
[default]
aws_access_key_id=your-access-key
aws_secret_access_key=your-secret-key
~/.aws/config:
[default]
region=us-east-1
For more information regarding AWS SDK configuration options, please refer to Setting_AWS_Credentials
⚠️ Ifintegrations.aws.credentialsis not set inapp-config.yaml, each client is still created — the starter logs a warning and falls back to the AWS SDK's default credentials provider chain (environment variables, shared~/.aws/credentialsfile, or an attached IAM role), so explicit config is optional in environments like EC2/ECS/Lambda.
npm install @aws-sdk/client-dynamodbAdd the AWS region of your DynamoDB to the config path:
integrations:
aws:
dynamodb:
region: "eu-central-1"@Service()
export class SampleService {
constructor(private readonly dynamoDBClient: DynamoDBClient) {}
async listTables(): Promise<void> {
const command = new ListTablesCommand({});
const response = await this.dynamoDBClient.send(command);
console.log("DynamoDB Tables:", response.TableNames);
}
}npm install @aws-sdk/client-s3Add the AWS region of your S3 bucket to the config path:
integrations:
aws:
s3:
region: "eu-central-1"@Service()
export class SampleService {
constructor(private readonly s3Client: S3Client) {}
async listBuckets(): Promise<void> {
const command = new ListBucketsCommand({});
const response = await this.s3Client.send(command);
console.log("S3 Buckets:", response.Buckets);
}
}npm install @aws-sdk/client-secrets-managerAdd the AWS region of your Secrets Manager to the config path:
integrations:
aws:
secrets:
region: "eu-central-1"@Service()
export class SampleService {
constructor(private readonly secretsClient: SecretsManagerClient) {}
async getSecret(secretName: string): Promise<void> {
const command = new GetSecretValueCommand({SecretId: secretName});
const response = await this.secretsClient.send(command);
console.log("Secret Value:", response.SecretString);
}
}npm install @aws-sdk/client-snsAdd the AWS region of your SNS topic to the config path:
integrations:
aws:
sns:
region: "eu-central-1"@Service()
export class SampleService {
constructor(private readonly snsClient: SNSClient) {}
async publishMessage(topicArn: string, message: string): Promise<void> {
const command = new PublishCommand({TopicArn: topicArn, Message: message});
await this.snsClient.send(command);
console.log("Message sent to SNS");
}
}npm install @aws-sdk/client-sqsAdd the AWS region of your SQS queue to the config path:
integrations:
aws:
sqs:
region: "eu-central-1"@Service()
export class SampleService {
constructor(readonly sqsClient: SQSClient) {}
async sendMessage(queueUrl: string, messageBody: string): Promise<void> {
const command = new SendMessageCommand({QueueUrl: queueUrl, MessageBody: messageBody});
await this.sqsClient.send(command);
console.log("Message sent to SQS");
}
}import {SqsListener, MessageEnvelop} from "@nodeboot/starter-aws";
@Service()
export class SampleService {
// Using SQS Queue URL hardcoded
@SqsListener("https://sqs.us-east-1.amazonaws.com/123456789012/my-queue")
async onMessage(message: MessageEnvelop): Promise<void> {
console.log("Message received from SQS");
}
}
@Component()
export class SampleComponent {
// Using SQS queue url with a config placeholder
@SqsListener("${com.example.aws.sqs.queue-url}")
async onMessage(message: MessageEnvelop): Promise<void> {
console.log("Message received from SQS");
}
}In this last case you need provide the config path in your app-config.yaml file:
com:
example:
aws:
sqs:
queue-url: "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue"
@SqsListeneronly registers when the current active profiles satisfy any@Profile(...)metadata declared on the target class (see@nodeboot/core's@Profiledecorator). If the profiles don't match, or AWS SQS isn't enabled via@EnableAws()/integrations.aws.sqs.region, the listener logs a warning and is skipped instead of throwing.
Every @SqsListener handler receives a MessageEnvelop<M> rather than the raw sqs-consumer Message:
type MessageEnvelop<M = JsonObject> = {
messageId: string; // the SNS notification's id, or the SQS message id
timestamp: string; // the SNS notification's Timestamp, or the SQS SentTimestamp (ISO 8601)
signature: string; // the SNS signature; empty for a message sent straight to SQS
message: M; // the JSON-parsed payload (the string itself when it is not JSON)
raw: Message; // the SQS message as received
};Both kinds of queue messages are supported:
- Sent straight to the queue (
SendMessage):messageis the parsed body. - Delivered by an SNS topic subscription (raw message delivery off): the notification is unwrapped and
messageis its parsedMessage.
A body that is not JSON is passed as a string; parsing never fails the message.
@SqsListener("${com.example.aws.sqs.queue-url}")
async onMessage(envelop: MessageEnvelop<{orderId: string}>): Promise<void> {
console.log(`Processing order ${envelop.message.orderId} (messageId=${envelop.messageId})`);
}The second argument configures the consumer (see sqs-consumer's ConsumerOptions):
@SqsListener("${com.example.aws.sqs.queue-url}", {
batchSize: 10, // messages per receive, handled concurrently (default 1)
waitTimeSeconds: 20, // long polling (default 20)
visibilityTimeout: 60, // seconds (default: the queue's)
handleMessageTimeout: 30_000, // ms; a slower handler fails its message
})
async onMessage(envelop: MessageEnvelop): Promise<void> {}The queue URL must have the path /<12-digit account id>/<queue name> on any http(s) host: AWS URLs
(https://sqs.<region>.amazonaws.com/...), FIFO queues (.../orders.fifo) and local emulators. For LocalStack or
ElasticMQ, point the client at the emulator:
integrations:
aws:
sqs:
region: "us-east-1"
endpoint: "http://localhost:4566"Every listener stops polling on application shutdown (SIGINT/SIGTERM), before other shutdown hooks run; a message
being handled finishes. stopSqsListeners() stops them on demand.
- The queue is polled continuously for messages using long polling.
- Throwing an error (or returning a rejected promise) from the handler function will cause the message to be left on the queue. An SQS redrive policy can be used to move messages that cannot be processed to a dead letter queue.
- By default messages are processed one at a time – a new message won't be received until the first one has been processed. To process messages in parallel, pass
{batchSize}in the listener options (above).- It's also important to await any processing that you are doing to ensure that messages are processed one at a time.
- By default, messages that are sent to the handleMessage and handleMessageBatch functions will be considered as processed if they return without an error.
- To acknowledge individual messages, please return the message that you want to acknowledge if you are using handleMessage or the messages for handleMessageBatch.
- To note, returning an empty object or an empty array will be considered an acknowledgement of no message(s) and will result in no messages being deleted. If you would like to change this behaviour, please use the alwaysAcknowledge option detailed here.
- By default, if an object or an array is not returned, all messages will be acknowledged.
- To acknowledge individual messages, please return the message that you want to acknowledge if you are using handleMessage or the messages for handleMessageBatch.
- Messages are deleted from the queue once the handler function has completed successfully (the above items should also be taken into account).
NodeBoot AWS Starter simplifies AWS client integration using dependency injection and dynamic configuration.
For further information, refer to the official AWS SDK documentation: AWS SDK v3.