Welcome to the Serverless Lambda Boilerplate! This project is designed to streamline the development of serverless applications using AWS Lambda and Prisma. It's built with TypeScript and includes setup for local development and deployment scripts to get you started quickly.
- Serverless Framework: Configure and deploy AWS Lambda functions easily.
- Prisma ORM: Robust database management and schema migration support.
- TypeScript: Strongly typed codebase for reliability and maintainability.
- Local Development: Local server simulation for easy development and testing.
Here's a brief overview of the main components of this boilerplate:
src/api/*
: Contains module-related controllers, services, and validators.src/core
: Core functionalities including middleware and HTTP models.src/prisma
: Prisma service and schema for ORM._templates
: Hygen templates for quickly generating new modules.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
- Node.js (LTS version recommended)
- AWS CLI configured with appropriate permissions
- Serverless CLI (
npm install -g serverless
)
Clone the repository:
git clone https://github.com/MateoCerquetella/serverless-lambda-boilerplate.git
cd serverless-lambda-boilerplate
Install dependencies:
npm install
Setup environment variables:
Create a .env
file in the root of your project and update it with your environment-specific details:
DATABASE_URL="your-database-url"
CORS_ALLOW_ORIGIN_1="http://localhost:3000"
AWS_ACCESS_KEY_ID="your-aws-access-key"
AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
REGION="your-aws-region"
Generate Prisma client:
npm run prisma:generate
Prisma Migrations allow you to reliably evolve your database schema with ease. These migrations are version-controlled schema changes, which can be applied in a staging or production environment in a predictable way.
To set up your database and create your first migration, follow these steps:
-
Set Database URL: Ensure that your
.env
file contains the correctDATABASE_URL
. This URL should point to your database, where Prisma will manage the schema migrations.Example
.env
entry:DATABASE_URL="postgresql://username:password@localhost:5432/mydb"
-
Create the First Migration: Run the following command to create your first migration. The migration will include the initial schema setup based on your current Prisma schema.
npm run prisma:migration:new -- --name first_migration
This command will generate SQL migration files within the
prisma/migrations
directory, which describe the steps necessary to reach your desired schema state.
To apply migrations to your database:
npm run prisma:migration:deploy
This command will apply all pending migrations in the order they were created to the database specified in your DATABASE_URL
. It's a safe way to update your database schema as part of your deployment process.
Whenever you make changes to your Prisma schema file (schema.prisma
), you will need to generate a new migration. These migrations capture incremental changes to your database schema.
To create a new migration after updating your schema:
npm run prisma:migration:new -- --name descriptive_migration_name
This will generate a new set of migration files reflecting changes since the last migration, ensuring that your schema changes are version-controlled and deployable.
To start the local development server:
npm run dev
This will start the Serverless Offline plugin, simulating AWS Lambda and API Gateway on your local machine.
To deploy your application to AWS:
npm run deploy:dev
This script will set up your environment, generate the necessary Prisma client, and deploy your application to AWS using the development stage configuration.
This boilerplate comes equipped with a module generator script that makes it easy to scaffold new modules quickly and consistently. Each module includes a set of predefined files such as controllers, services, validators, and handler setups, tailored for serverless applications.
To create a new module, you can use the generate:module
script included in the package.json
. This script automates the creation of necessary files and configurations for a new module, following the defined templates in the _templates
directory.
Here’s how to generate a new module named "People":
npm run generate:module -- --name people --route people
When you run the generate:module
command, the following will happen:
- Module Directory: A new directory under
src/api
will be created with the name you specified. - Files Created:
- A new
controller.ts
for managing request handling. - A
service.ts
for business logic associated with the module. - A
validator.ts
for input validation. - Handler files within a
handlers
subdirectory for different operations like create, read, update, and delete. - A
functions.yml
file for defining serverless functions specific to this module.
- A new
- Routing Setup: The route you specify will be used to configure the endpoints in your serverless setup.
You can customize the templates used for module generation by modifying the EJS templates located in the _templates/module/new
directory. These templates define the structure and content of the files that are generated for each new module.
By adjusting these templates, you can ensure that every new module conforms to your project's coding standards and architectural decisions.
After generating a new module, don't forget to integrate it into your main application setup. This includes:
- Adding any new dependencies required by the module.
- Ensuring that the new serverless functions defined in the
functions.yml
of the module are correctly referenced in the mainserverless.yml
. - Registering any new routes and handlers in your application's routing and serverless configuration.
This process ensures that your new module is fully functional and ready to be developed further or deployed as part of your application.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (`git commit -m 'Add some AmazingFeature'')
- Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Mateo Cerquetella