NextJS SDK 2.0

info

We released a new major version of our SDK. You can now download version 2 🎉

The ServerlessQ SDK allows you a native integration into your Next.JS application. If you're also deployed on Vercel we can automatically fill in URLs as well. Let's see how you can use it.

Setup

Installation

pnpm

pnpm add @serverlessq/nextjs

yarn

yarn add @serverlessq/nextjs

npm

npm i @serverlessq/nextjs

Add API Token

You can find your API key in your settings. Add it to your environment variables, e.g. into your .env file.

SERVERLESSQ_API_TOKEN=...

Checkout our Vercel Integration to set it up automatically.

Wrap nextConfig into withServerlessQ

Next, you need to add the withServerlessQ wrapper. This will activate the local file watcher and start a local proxy once you start the dev server.

const { withServerlessQ } = require("@serverlessq/nextjs");

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = withServerlessQ(nextConfig);

Create a Queue

Next you can create your first queue. For that create an API function, e.g. pages/api/queue.ts. In this function you import the queue from @serverlessq/nextjs and create a new queue.

Add the options:

• name: Name of the queue. This needs to be unique within your account
• route: Path to the queue. We need this to call the correct path.
• retries: How often should failed requests be retried?

pages/api/queue

import { Queue } from "@serverlessq/nextjs";
import { NextApiRequest, NextApiResponse } from "next";

export default Queue({
  options: {
    name: "image-queue",
    route: "api/image-queue",
    retries: 3,
  },
  handler: async (_req: NextApiRequest, res: NextApiResponse) => {
    res.status(200).json({ status: "Image transformed ✅" });
  },
});

Your handler function is the business logic you want to execute. In our example we simply return a JSON object.

If you started your dev server and you've hit save you should now see a new queue in your dashboard:

Enqueue a Job

You can now import your queue and enqueue jobs. You can do this either from getServerSideProps or from another API function. You can't do it from the frontend since you don't want to expose your API key.

API Function

pages/api/enqueue

import { NextApiRequest, NextApiResponse } from "next";
import ImageQueue from "./image-queue";

export default async function enqueue(
  _req: NextApiRequest,
  res: NextApiResponse
) {
  const result = await ImageQueue.enqueue({
    method: "GET",
    body: { path: "URL" },
  });
  return res.send("OK");
}

getServerSideProps

pages/index -> gSSP

import ImageQueue from "./api/image-queue";

export async function getServerSideProps() {
  const result = await ImageQueue.enqueue({
    method: "POST",
    body: { email: "test@mail.com" },
  });

  return {
    props: {
      result,
    }, // will be passed to the page component as props
  };
}

export default function Home() {
  return <div>...</div>;
}

Here you simply send a job to your queue with a defined HTTP method. Thats it ✨

Features

Filewatcher

One feature to enhance the local development experience is the local filewatcher. Once you've wrapped your nextConfig with the function withServerlessQ we automatically detect oyur local queues and crons and deploy them automatically!

During development mode we prefix them with DEV_, during build time we remove this prefix.

Local Proxy

The second major feature is the local proxy. Once your deveopment server is started we start a local proxy. This proxy acts as the target for dev resources like queues or crons. This allows you to test your functions locally. Every request will be sent to your local machine.