Skip to main content

Local Development - SDK & NGROK

If you use our SDK for interacting with ServerlessQ you will quickly see that it is required to have a deployed webhook URL. Especially for the start of a new project this is often not the case.

To overcome this issue you need to route your webhook requests to your local machine. Since ServerlessQ runs in the cloud it is necessary to route requests to your machine.

This is easily possible with ngrok. With ngrok you launch a tunnel between a webhook URL they provide and your local machine.

Sign up for Ngrok​

Go to the ngrok dashboard and create an account.

Install & Configure Ngrok CLI​

After that you will be promted to install the CLI.

On Mac you can simply install it with homebrew

brew install --cask ngrok

After that you need to add your authentication token

ngrok config add-authtoken XXX

All of this will be shown to you after you sign up for an account.

Start Agent on your machine​

Now you can start an agent on your machine. Simply enter the following command

ngrok http 3000

3000 is the port your application runs on. You need to change it in case you're using another port!

Get Ngrok URL​

Head over to your Ngrok Dashboard -> Tunnels -> Agents

Settings with API token

You will now see your agent running.

By clicking on the agent you can find your webhook URL. All calls to this URL will go to your local machine.

Settings with API token

Define Consumer API​

If you create your Queue you can define an URL that should be called in case your system runs not on Vercel. The SDK checks the environment variable VERCEL for that.

You can simply pass your ngrok URL to the queue option urlToOverrideWhenRunningLocalhost and append your path to the Queue, for examlpe api/queue.

Here an example:

// pages/api/queue
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://abc.ngrok.io/api/queue" } // Additional optional options
);