@awsless/awsless

Awsless - Infrastructure as a code

Table of Contents

• Table of Contents
• Features
• Installing
  • Package manager
• Getting Started
  • Base Configuration
  • Modular Stacks
  • Deploying
  • Stack Updates
  • Smart Helpers: Call Your Infra Like Functions
• Testing Stacks
• Core Resources
  • Function - AWS Lambda
    • Basic usage
    • Advanced usage
  • Task
    • Basic usage
    • Advanced usage
  • Table
    • Usage
  • Queue
    • Usage
  • Topics
    • Usage
  • Crons
    • Usage
    • RPC
• Smart Functions - Call your infra from code
  • Examples
    • Lambda Function
    • Task
    • Queue
    • Topic
    • Config

Features

🪶 AWS development using JSON config with best practices baked in

⚡ Deploy APIs, functions, databases, queues, and more — all in one place

🔒 Secure by default with IAM-based permissions and least privilege

🌍 First-class support for AWS Lambda, DynamoDB, SQS, EventBridge, and more

🧪 Built-in local development and testing utilities

🔄 Automatic function bundling with support for ES modules and TypeScript

🔄 Types generatation for all resources that can be acessed anywhere in the code

Installing

Package manager

Using npm:

$ npm i @awsless/awsless

Using pnpm:

$ pnpm i @awsless/awsless

Getting Started

In an Awsless project, your infrastructure is organized into modular stack files, each with its own purpose, and a shared base configuration. Before you begin, make sure you have the AWS CLI installed.

Base Configuration

This is your shared app configuration, which acts as the base stack for the entire project. This should exist in the root of your project. app.json

{
  "name": "hello-world",
  "region": "eu-west-1",
  "profile": "test",
  "defaults": {
    "alerts": {
      "debug": "[e-mail]"
    }
  }
}

🔑 Key Fields

• name: Name of your application.

• region: AWS region where you want to deploy your infrastructure.

• profile: Your AWS CLI profile to use for deployment.

Modular Stacks

Each feature/module of your application can be defined as a separate stack file. These live in their own folders and are completely independent.

Example - auth/stack.json

{
	"name": "auth",
	"functions": {
		"verify": "./src/lambda.ts" // AWS Lambda
	},

}

Example - rate/stack.json

{
	"name": "rate",
	"functions": {
		"limit": "./src/lambda.ts" // AWS Lambda
	},

}

You can create as many stack files as needed, each targeting different parts of your application.

Deploying

Deploy all stacks

$ pnpm awsless deploy

Deploy individual stack

$ pnpm awsless deploy rate

Deploy multiple stacks

$ pnpm awsless deploy rate auth

Deploy base stack

$ pnpm awsless deploy base

Stack Updates

Awsless makes it simple to remove infrastructure when it's no longer needed.

🧼 Delete a Specific Stack

$ pnpm awsless delete rate

💣 Delete All Stacks

pnpm awsless delete

⚠️ This will remove all deployed resources associated with your stacks. Use with caution!

♻️ Updating or Replacing Resources When you modify a stack file and run a deployment again, Awsless will:

• Update existing resources if changes are detected.

• Delete resources that are removed from the stack file.

• Create new resources as needed.

• This ensures your infrastructure always reflects the current state of your stack configuration — no manual cleanup required.

Smart Helpers: Call Your Infra Like Functions

Once your stacks are defined, Awsless provides built-in helpers like Fn, Queue, and Task to let you interact with your infrastructure directly from your application code — no wiring or manual setup needed.

To enable full type support for these resources, run:

$ pnpm run dev

This will watch your project and automatically generate type definitions for all the resources you've created.

You can then use them seamlessly inside your Lambda functions:

Now from one lambda function we can all any infra like

import { Queue, Fn } from '@awsless/awsless'

// Call a Lambda function from another stack
await Fn.rate.limit()

// Push a message to a queue
await Queue.notifications.send({ userId: 123 })

💡 These helpers are fully typed and auto-wired, making your code clean, safe, and easy to maintain.

Testing Stacks

Awsless supports built-in testing for your stacks to ensure everything works as expected before deployment.

You can define test folder in each stack

{
	"name": "rate",
	"test": "./path/to/test/folder"
}

exmaple test case rate/test/utils.ts

describe('test', () => {
	it('hello world', async () => {
		expect(1 + 2).toStrictEqual(3)
	})
})

🔍 Run Tests Manually

$ pnpm awsless test rate

This will look for a defined test folder inside the rate stack directory and run any defined tests inside here.

🛡️ Tests Run Automatically Before Deploy Whenever you run pnpm awsless deploy, Awsless will automatically:

• Check if a test/ folder exists for each stack

• Run the tests for that stack

• Block the deployment if any tests fail

Core Resources

Function - AWS Lambda

Basic usage

{
	"functions": {
		"FUNCTION_NAME": "/path/to/function"
	}
}

Advanced usage

You can also customize your Lambda function with additional parameters like memory size, timeout, environment variables, and more:

	"functions": {
		"test": {
			"code": "/path/to/function",
			"memorySize": 512
		}
	},

Task

A Task in Awsless is an asynchronous Lambda function designed for background processing. You can trigger a task and immediately move on — Awsless handles the execution in the background, including retries and logging on failure.

Basic usage

{
	"tasks": {
		"FUNCTION_NAME": "/path/to/function"
	}
}

Advanced usage

You can also customize your Lambda function with additional parameters like memory size, timeout, environment variables, and more:

	"tasks": {
		"test": {
			"code": "/path/to/function",
			"memorySize": 512
		}
	},

Table

The tables feature in Awsless allows you to define fully managed, serverless DynamoDB tables directly in your stack configuration.

Usage

{
	"tables": {
		"TABLE_NAME": {
			"hash": "id",
			"sort": "user",
			"indexes": {
				"list": {
					"hash": "createdAt",
					"sort": "id"
				}
			}
		}
	}
}

🔑 Key Fields:

• hash - Primary key
• sort - Sort key
• indexes - Define secondary index here

Queue

This allows you to define a queue along with the consumer lambda.

Usage

{
	"queues": {
		"sendMail": {
			"consumer": "/path/to/lambda/file",
			"maxConcurrency": 2,
			"batchSize": 5
		}
	}
}

Topics

This allows you to define a topic along with the subscriber lambda.

Usage

{
	{
  "topics": [ "TOPIC_NAME" ],
  "subscribers": {
    "TOPIC_NAME": "topic-consumer.ts",
  }
}
}

Crons

Awsless uses AWS EventBridge to provide fully managed, serverless cron jobs — perfect for running scheduled tasks like cleanups, reports, or recurring syncs.

Usage

{
	"crons": {
		"CRON_NAME": {
			"schedule": "1 day",
			"consumer": "cron-consumer.ts"
		}
	}
}

🔑 Key Options:

• schedule: The interval or cron expression to define when the job should run (e.g., "1 day" or "cron(0 12 * _ ? _)").

• consumer: Path to the Lambda function that should be triggered on schedule.

RPC

Awsless allows you to easily expose any Lambda function as a type-safe RPC (Remote Procedure Call) endpoint for your frontend.

The request and response types are automatically inferred from your Lambda function's payload and return value, giving you end-to-end type safety.

{
	"rpc": {
		"base": {
			// base resource defined in app.json
			"SendFriendRequest": "/path/to/lambda"
		}
	}
}

Smart Functions - Call your infra from code

With awsless, you can interact with your infrastructure directly from your code. awsless generates all necessary types for you, allowing seamless access to your resources.

To set up, define your stacks and run:

$ pnpm awsless dev

This command will generate the required types and mappings, enabling you to access infrastructure components in your code effortlessly.

Resources are accessible via their stack name and resource name. For instance, if a Lambda function exists within a stack named player, you can access its resources using:

player.{resourceName}

Examples

Lambda Function

Calling a function named limit inside the rate stack:

import { Fn } from '@awsless/awsless'

await Fn.rate.limit({ userId: 'test' })

Task

import { Task } from '@awsless/awsless'

await Task.mail.send({ msg: 'hi', userId: 'test' })

Queue

Sending a message to a queue

import { Queue } from '@awsless/awsless'

await Queue.mail.send({ msg: 'hi', userId: 'test' })

Topic

Publish a message to SNS topic

import { Topic } from '@awsless/awsless'

await Topic.transaction.credit({ amount: 10, userId: 'test' })

Config

Reading a secret configuration value:

import { Config } from '@awsless/awsless'

const key = await Config.API_KEY