Skip to navigation

Development Proxy

In production, your app runs inside the Whop iframe behind a reverse proxy that injects the x-whop-user-token header on every request. Every Whop app verifies that token via whopsdk.verifyUserToken, so you need the same header on localhost to test against real users. The dev proxy injects it for you.

Pick your setup

Two installation modes. Both ship the same proxy binary; the difference is whether the proxy spawns your dev server or runs alongside it.

Wrapped (Node/JS)Standalone
Best forNext.js, Express, anything with a node-based dev scriptPython, Ruby, Go, anything non-JS
How it runswhop-proxy --command 'next dev' spawns your serverYour server runs separately on a port; the proxy forwards to it
PortOne port (proxy + server)Two ports (proxy on 3000, server on e.g. 5000)
Installpnpm add -D @whop-apps/dev-proxypnpm dlx @whop-apps/dev-proxy --standalone (no install needed)

NextJS / Javascript app

1

Add the proxy as a dev dependency

pnpm add -D @whop-apps/dev-proxy
2

Update your package.json dev script

Update your package.json dev script to include the proxy.

"scripts": {
    "dev": "whop-proxy --command 'next dev --turbopack'",
}

You can update the dev command to match your framework requirements. You can also wrap other commands with the proxy in a similar way.

3

Run the proxy

pnpm dev

Standalone mode (other frameworks)

1

Run your app locally

Run your app on your local machine on some port, for example 5000.

uvicorn main:app --port 5000
2

Run the proxy in standalone mode

pnpm dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000

This will run the proxy as an independent process. It will start a server on port 3000 and forward requests to port 5000 and append the user token in the headers.

Proxy Command Options

The proxy can be configured using the following command line options:

Usage: pnpm dlx @whop-apps/dev-proxy [options]
Options:
--proxyPort <port>      The port the proxy should listen on (3000 by default)
--upstreamPort <port>   The port the upstream server is listening on (set automatically by default)
--npmCommand <command>  The npm command to run to start the upstream server (dev by default)
--command <command>     The command to run to start the upstream server (npm run dev by default)
--standalone            Run the proxy as an independent process proxying requests from one port to another port. Ignores the command / npmCommand options.

Next steps

Authentication

Verify the iframe user token in the same code locally and in production.

Listen to webhooks

Forward Whop webhooks to localhost while developing (use ngrok or Cloudflare Tunnel).

Build app views

Set up the iframe entry points your app will render inside.

Request permissions

Configure the scopes your app needs before publishing.