Local development
Upstash Workflow require a publicly accessible API endpoint to function. While we plan to offer a native solution in the future, please use a third-party tunneling service for now.
Local development with ngrok (recommended)
The easiest way to make a local URL publically available is ngrok, a free tunneling service.
Create an account on dashboard.ngrok.com/signup and follow the setup instructions to download the ngrok CLI and connect your account. This process takes only a few minutes and is totally free.
For example on MacOS, you can connect your account like this:
Or on Windows:
Once you have installed the ngrok CLI, add your ngrok-issued auth token like this:
ngrok config add-authtoken <YOUR-AUTH-TOKEN>
and replace <YOUR-AUTH-TOKEN>
with your actual auth token.
Start the tunnel
Make your local server available publically by running the following command:
ngrok http <PORT>
for example, if your Next.js server is running on port 3000
, the command is:
ngrok http 3000
The output will look something like this:
Session Status online
Account <YOUR-NAME> (Plan: Free)
Version 3.1.0
Region Europe (eu)
Latency -
Web Interface http://127.0.0.1:4040
Forwarding https://e02f-2a02-810d-af40-5284-b139-58cc-89df-b740.eu.ngrok.io -> http://localhost:3000
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
The long URL in the Forwarding
line serves the same purpose as your localhost URL, the only difference being that it is publically accessible. We need this URL to make our workflow available to QStash for local development, either as the baseUrl
parameter or the UPSTASH_WORKFLOW_URL
environment variable (both options provide the same functionality).
Note: The UPSTASH_WORKFLOW_URL
environment variable is only necessary for local development. In production, the baseUrl
parameter is automatically set and can be omitted.
Ensure that the port of your local server matches the one you’re using with ngrok. For example, if your server is
running on port 8080, use ngrok http 8080
.
Was this page helpful?