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.