Skip to main content

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 add @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:

New dev queue created

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.

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");
}

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.