Skip to main content

Quick Start

Get up and running with Serverless Monolith in under 5 minutes.

Project Structure​

First, create a project structure that Serverless Monolith can discover:

my-project/
├── src/
│   └── modules/
│       └── user/
│           ├── functions.yml
│           └── handlers/
│               ├── create/
│               │   └── index.ts
│               └── list/
│                   └── index.ts
├── monolith.config.ts
└── package.json

Configuration File​

Create a monolith.config.ts in your project root:

import { MonolithConfig } from '@serverless-monolith/core';

export default {
  discovery: {
    modulesDir: 'src/modules',
    functionsFile: 'functions.yml',
  },
  logging: {
    enabledCategories: ['adapterStartupInfo', 'httpRequestInfo'],
    showRoutesTable: true,
  },
} satisfies MonolithConfig;

Define Your Functions​

Create a functions.yml in your module directory:

# src/modules/user/functions.yml

createUser:
  handler: handlers/create/index.handler
  events:
    - http:
        path: users
        method: POST
        cors: true

listUsers:
  handler: handlers/list/index.handler
  events:
    - http:
        path: users
        method: GET
        cors: true

Create Handlers​

Create your handler functions:

// src/modules/user/handlers/create/index.ts
import { APIGatewayProxyHandler } from 'aws-lambda';

export const handler: APIGatewayProxyHandler = async (event) => {
  const body = JSON.parse(event.body || '{}');
  
  // Your business logic here
  const user = {
    id: Date.now().toString(),
    ...body,
  };

  return {
    statusCode: 201,
    body: JSON.stringify(user),
  };
};
// src/modules/user/handlers/list/index.ts
import { APIGatewayProxyHandler } from 'aws-lambda';

export const handler: APIGatewayProxyHandler = async () => {
  // Your business logic here
  const users = [
    { id: '1', name: 'John Doe' },
    { id: '2', name: 'Jane Doe' },
  ];

  return {
    statusCode: 200,
    body: JSON.stringify(users),
  };
};

Start the Server​

Create a start script:

// start.ts
import { MonolithServer } from '@serverless-monolith/core';
import path from 'path';

const server = MonolithServer.create(
  path.resolve(__dirname, './monolith.config.ts'),
  { port: 4005, cors: true }
);

server.start().then(() => {
  console.log('Server started on http://localhost:4005');
});

Run the server:

npx tsx start.ts

Test Your API​

# List users
curl http://localhost:4005/api/http/user/users

# Create a user
curl -X POST http://localhost:4005/api/http/user/users \
  -H "Content-Type: application/json" \
  -d '{"name": "New User"}'

Next Steps​