Enhance Express.js Apps with Cloud Resources

In this guide we'll be scaffolding a new Express.js application and including the Nitric framework to allow for the addition of other cloud resources like topics, queues and buckets.

Prerequisites

To complete this guide you'll need the following:

Node.js installed locally
Nitric CLI installed
(optional) Your choice of an AWS, GCP or Azure account

Getting Started

Let's start by setting up a Nitric project and adding Express.js:

nitric new express-example js-starter

Then install dependencies and add express:

cd express-example
yarn install
yarn add express

You can go ahead and open this new project in your editor of choice. You should see a project structure similar to:

├── services
│   ├── hello.js
├── node_modules
│   ├── ...
├── .gitignore
├── index.js
├── nitric.yaml
├── package.json
├── README.md
└── yarn.lock

In this structure you'll notice the services folder. By default, this is where Nitric expects the entrypoint code for your application. However, that's just a convention, we can change that to anything else that suits our needs.

Let's start by replacing the default hello.js service with an app.js file ready for the Express.js application:

rm ./services/hello.js

touch ./services/app.js

Now, let's add some express code to get things started.

import express from 'express'
import { http } from '@nitric/sdk'
const app = express()

app.get('/', (req, res) => {
  res.send('Hello World!')
})

http(app)

If you're familiar with Express.js you'll notice this example doesn't call app.listen. The Nitric http function takes care of that, as well as binding the application to the correct port in each environment.

At this point, we're ready to start testing locally.

nitric start

Your express application will now be running with Nitric acting as a proxy. We can test this in another terminal or web browser.

curl http://localhost:4001
Hello World!

Enhancing Express.js with Nitric

With everything working so far, now is a good time to see how we can add new resources to the Express app using Nitric. In this example, let's add a pub/sub topic which allows us to perform work in the background, but still respond quickly via the HTTP API.

You can update the app.js file like so:

import express from 'express'
import { http, topic } from '@nitric/sdk'

const app = express()
const workRequests = topic('work-requests').allow('publish')

app.get('/', async (req, res) => {
  await workRequests.publish()
  res.send('Hello World!')
})

http(app)

We'll also add a new service to do the background work:

touch services/worker.js

Add this code to that file:

import { topic } from '@nitric/sdk'

const sleep = (ms) => new Promise((res) => setTimeout(res, ms))

topic('work-requests').subscribe(async (ctx) => {
  console.log('Starting new request')
  // wait for 2 seconds to simulate a long running task
  await sleep(2000)
  console.log('Request processed')
})

Now, when you browse to localhost:4001 you'll notice that the console outputs these lines with a 2 second delay between each line:

Starting new request
Request processed

You should notice that while the background worker takes 2 seconds to finish, the HTTP request GET: / still returns instantly.

At this point, we can stop the running application and try to deploy it to a cloud provider.

Deploy to the cloud

This is where the true value of Nitric shines. You don't need to perform any manual cloud deployment activities or add solutions like Terraform to get this project into your cloud environment, Nitric takes care of that for you.

To perform the deployment we'll create a stack, stacks give Nitric the configuration needed for a specific cloud instance of this project, such as the provider and region.

The new stack command can help you create the stack by following prompts.

nitric stack new

This command will create a file named nitric.dev.yaml, with contents like this:

provider: nitric/aws@1.1.0
region: us-east-1

With the stack file in place we can run the deployment:

nitric up

Go ahead and test your new Express+Nitric app in the cloud, you can start with the API Gateway URL returned by the up command.

When you're done with the cloud deployment you can tear it down using the nitric down command.

What's next?

Now that you have the basics down, try exploring other Nitric resources available to enhance your app.