Development Proxy

Run the Whop development proxy to replicate production authentication and iframe behavior during development.

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 through whopsdk.verifyUserToken, so you need the same header on localhost to test with real users. The development proxy injects it for you.

Pick your setup

There are two installation modes. Both ship the same proxy binary. The difference is whether the proxy spawns your development server or runs alongside it.

	Wrapped (Node/JS)	Standalone
Best for	Next.js, Express, anything with a node-based development script	Python, Ruby, Go, anything non-JS
How it runs	whop-proxy --command 'next dev' spawns your server	Your server runs on a port, and the proxy forwards to it
Port	One port (proxy + server)	Two ports (proxy on 3000, server on e.g. 5000)
Install	pnpm add -D @whop-apps/dev-proxy	pnpm dlx @whop-apps/dev-proxy --standalone (no install needed)

Next.js and JavaScript app

1. Add the proxy as a development dependency

   pnpm

   pnpm add -D @whop-apps/dev-proxy
   
2. Update the dev script in package.json

   Update the dev script in package.json 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

   pnpm dev
   

Standalone mode (other frameworks)

1. Run your app locally

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

   Python + FastAPI

   uvicorn main:app --port 5000
   
2. Run the proxy in standalone mode

   pnpm

   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

Configure the proxy with 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.