ServerlessQ JavaScript SDK 1.0

We've got a huge announcement 🎉

A few weeks ago we published our new JavaScript/TypeScript SDK to make using ServerlessQ easier!

You can find the SDK docs here and the actual live npm package here

Goal of the SDK

The main goal of the SDK is to interact with ServerlessQ without the need of visiting the UI. The only reason you need to visit the UI is to create an account and obtain your API token.

Other than that we want to make the usage of ServerlessQ as simple as possible. With an amazing product like Vercel, we can do that by simply integrating many of its capabilities. For example, we use the environment variables of Vercel to interact with the correct URL.

Functions of the SDK

The main functionality of the SDK is the usage of Message Queues.

Next.js in combination with Vercel gives you the amazing capability of hosting Serverless Functions in your pages/api folder. All functions that will be created there will be executed in a serverless lambda environment.

We wanted to make use of that by enabling these functions to run in the background.

With the SDK you can simply create a queue from these API functions and define which business logic will be executed. Let's see an example here:

// pages/api/queue
import { Queue } from "@serverlessq/nextjs";


export default Queue(
  "SendNewsletter" // Name of the queue,
  "api/queue" // Path to this queue,
  async (req, res) => { // Handler function. This will be executed once you enqueue a job.
    const result = await doSomethingImportant();
    console.log("Queue Job", result);
    res.send("finished");
  },
  { retries: 1, urlToOverrideWhenRunningLocalhost: "https://mock.codes/201" } // Additional optional options
);

This code for example lives in the path pages/api/queue. Since it is in pages/api/ it is a serverless function and it can be executed by visiting the URL VERCEL_DEPLOYMENT_URL/api/queue.

By defining a Queue we wrap the actual NextJsApiHandler in our own function. Our function handles the interaction with the ServerlessQ system.

The queue is exported. That means on another API function, or in getServerSideProps you can simply import the queue and send messages to it.

// pages/api/enqueue or getServerSideProps
import { NextApiRequest, NextApiResponse } from "next";
import testQueue from "./queue";

export default async function enqueue(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const result = await testQueue.enqueue({ method: "GET" });
  res.send("OK");
}

All messages that will be sent to the queue will be executed in the background with the parameter you defined in the queue, for instance, a retry of 2.

You can have a look at a more detailed tutorial here.

What is the SDK actual doing in the background?

For those of you interested in what happens in the background.

Queue Creation

While wrapping the API function in the Queue object our SDK handles the creation of the queue.

1. Create the queue or get the queue ID if it already exists
2. Check if options have changed -> Change options, e.g. retries

Enqueueing a Message

Enqueueing the message is doing the following:

1. Check if the current system runs on Vercel (VERCEL environment variable set?)
2. Enqueue message with the correct target address -> Use VERCEL_URL and the defined API route.

With the second step, we cover all preview, development, and production environments 😎

Future Features

Of course, Message Queues and retries are just the beginning. Our goal is to have feature parity of all functions from ServerlessQ and the SDK. For now, that means we are actively integrating Cron Jobs into the SDK.

If you want to stay up-to-date with all news make sure to follow ServerlessQ on Twitter and sign up for our email list

Thanks ✌️

PS: Next up is our Vercel Integration 🚀