diff --git a/apps/api/package.json b/apps/api/package.json index 59a5ab37..b112a734 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -2,11 +2,12 @@ "name": "api", "private": true, "scripts": { - "dev": "concurrently \"pnpm:next\" \"pnpm:stripe\"", + "dev": "concurrently \"pnpm:next\" \"pnpm:stripe\" \"pnpm:ngrok\"", "next": "next dev -p 3002 --turbopack", "build": "next build", "start": "next start", "analyze": "ANALYZE=true pnpm build", + "ngrok": "ngrok http --url=your-domain-name 3002", "stripe": "stripe listen --forward-to localhost:3002/webhooks/stripe" }, "dependencies": { diff --git a/docs/authentication.mdx b/docs/authentication.mdx index 80762648..dad959be 100644 --- a/docs/authentication.mdx +++ b/docs/authentication.mdx @@ -19,4 +19,17 @@ Clerk uses webhooks to handle authentication events. These are handled in the `P ### Local Development -Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying your app to a "production" state Vercel project with development environment variables e.g. `staging-api.example.com`. Then you can add this URL to your Clerk project's webhook settings. +To test webhooks locally, you can use Ngrok to expose your local server to the internet. This allows Clerk to send webhooks to your local development environment. + +1. Install Ngrok by following the instructions on the [Ngrok website](https://ngrok.com/download). +2. Start your local development server and Ngrok by running the following command in the `api` app: + +```sh +pnpm dev +``` + +This will start the Next.js development server on port 3002, the Stripe CLI to forward webhooks to your local server, and Ngrok to expose your local server to the internet. + +3. Copy the forwarding URL provided by Ngrok (e.g., `https://.ngrok.io`) and add it to your Clerk project's webhook settings. + +4. Now you can test Clerk webhooks locally without needing to deploy your app to a staging environment. diff --git a/docs/setup.mdx b/docs/setup.mdx index 2b31dc16..c0b723e0 100644 --- a/docs/setup.mdx +++ b/docs/setup.mdx @@ -46,6 +46,12 @@ cd docs mintlify dev ``` +### Ngrok + +We use Ngrok to expose your local server to the internet for testing webhooks. You can read more about that [here](/authentication#local-development). + +Learn how to [install Ngrok](https://ngrok.com/download) for your operating system. + ### Accounts next-forge relies on various SaaS products. You will need to create accounts with the following services then set the API keys in your [environment variables](/env):