Getting started with serverless (offline)

Table of Content

In this tutorial I will explain step-by-step how to get started with your first serverless project using TypeScript in a local(offline) development environment by using the serverless offline-plugin.

What you need:

  • node.js (version 13)
  • a Text-Editor or a source-code-editor like Visual Studio Code
  • a terminal in which you can enter your commands (Visual Studio Code already ships with a terminal)

Before we begin some info:
In this example we are building an AWS Node.js-project.
The serverless-command doesn’t initialize the project as an npm-project (missing package.json). In fact, you don’t need the serverless-command for creating a node.js-project.
I’m using it here, because it is a starting-point in most tutorials.
I think the files which will be created here, are a good example and starting-point for most projects (even if the files and folder-structures change step-by-step).

You can especially benefit from a Serverless-Account and an AWS configuration, if you have one.
Here I am solely using serverless-offline, because I don’t think that a Hello World! needs to be deployed.

Additionally I am using the examples from serverless-offline to end up with my own running example (TypeScript + nodemon).

Step 1: Installing serverless, creating the project and adding the serverless-offline plugin

First we need to install serverless, if we haven’t already.

$ npm i -g serverless

After that, we need to execute serverless and follow the prompts.

During the prompts you will be asked 5 questions:

  1. No project detected. Do you want to create a new one? → Yes
  2. What do you want to make? → AWS Node.js
  3. What do you want to call this project? → getting-started-with-serverless
  4. Connect to Serverless-Account: Do you like to enable this? → No
  5. AWS Credentials: Do you want to set them up now? → No

On Windows the serverless-command won’t terminate. Feel free to press ctrl+c, if it does not terminate itself after the 5. question.

$ serverless

The project folder will be created upon completion.
cd into the new project directory.

$ cd ./getting-started-with-serverless

As you can see there, a package.json hasn’t been created. Because of this, we have to initialize our project-folder.

$ npm init -y

To add serverless and the serverless-offline-plugin, we need to execute this:

$ npm i --save-dev serverless serverless-offline@next

Add the serverless-offline plugin to the serverless.yml-configuration-file.
Currently the serverless.yml doesn’t yet contain a plugin-section, so simply append

  - serverless-offline

Finally, add a start-script into your package.jsonscripts:

"start": "serverless offline start",

Step 2: Getting the example running

Create a folder src in your project-root and move handler.js into it.

In serverless.yml find the section functionshello and right before the handler-part add an event-section.
The functions-entry should look like this:

      - http:
          method: get
          path: /hello
    handler: src/handler.hello

If you are adding the content without copy-paste:
Don’t forget to give method and path an extra indent.

After that we can run it offline to see if it works.

$ npm start

In the terminal-output you can see the address http://localhost:3000 and the URL for Swagger http://localhost:3000/documentation.
Now you can call the hello-lambda by opening the URL http://localhost:3000/hello.

You can execute the route via the swagger-ui, too. It’s a comfortable way to check if your routes work.

Step 3: Adding TypeScript

Don’t forget to terminate the server!

To add Typescript, we need to install some more packages.

$ npm i --save-dev @types/aws-lambda ts-node typescript

Create a tsconfig.json in your project-root and insert this content:

    "compilerOptions": {
        "target": "es5", 
        "module": "commonjs",
        "strict": true,   
        "esModuleInterop": true

Create a bridge.js in the src-folder with this content.

'use strict';

module.exports = require('./handler.ts');

Update the value of your handler-entry in your serverless.yml to src/bridge.hello

Rename handler.js into handler.ts and replace its content with this.

import { APIGatewayProxyEvent, APIGatewayProxyResult, Handler } from 'aws-lambda';

export const hello: Handler<APIGatewayProxyEvent,APIGatewayProxyResult> = async function hello(event, context, callback) {
  return {
    body: JSON.stringify({ message: 'Hello World!' }),
    statusCode: 200,

Start the server.

$ npm start

Step 4: Add nodemon for hot-reloading

Install nodemon package.

$ npm i --save-dev nodemon

Rewrite start-script in package.json.

"start": "nodemon -e js,ts,yml --ignore node_modules --exec serverless offline start"

Run it (npm start) and check the output of our new hello-TypeScript-handler.
Change in handler.ts the word World into Universe and save the file.
You will see in your terminal, that nodemon is restarting the server.
Open your browser and call the Hello-Handler-URL or refresh it, if it is already open.

Keep in mind
The browser doesn’t refresh by itself the current page, you have to do it manually.

That’s it!

Best Page Builder Plugin
Best Digital Asset Library
Find amazing stock images
Feel free to leave a comment
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x