Local Development

Upstash Workflow requires your application to be publicly accessible in production. For development, you can either run the QStash development server locally or set up a local tunnel to make your local server publicly accessible.

​

Development Server (Recommended)

Upstash Workflow is built on top of Upstash QStash. The QStash CLI provides a local development server that performs QStash functionality locally for development and testing purposes.

For detailed instructions on setting up the development server, see our QStash Local Development Guide.

Once your development server is running, update your environment variables to route QStash requests to your local server. This eliminates the need for tunneling during development.

The QStash CLI output will look something like this:

Upstash QStash development server is runnning at http://127.0.0.1:8080

A default user has been created for you to authorize your requests.
QSTASH_TOKEN=eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=
QSTASH_CURRENT_SIGNING_KEY=sig_7RvLjqfZBvP5KEUimQCE1pvpLuou
QSTASH_NEXT_SIGNING_KEY=sig_7W3ZNbfKWk5NWwEs3U4ixuQ7fxwE

Sample cURL request:
curl -X POST http://127.0.0.1:8080/v2/publish/https://example.com -H "Authorization: Bearer eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0="

Check out documentation for more details:
https://upstash.com/docs/qstash/howto/local-development

You should set the QSTASH_URL environment variable to point to your local server, along with the user credentials provided in the output.

​

Local tunnel with ngrok

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.