Satellite domain demo using Turborepo with Clerk, Next.js, and React

Introduction

Clerk is a developer-first authentication and user management solution. It provides pre-built React components and hooks for sign-in, sign-up, user profile, and organization management. Clerk is designed to be easy to use and customize, and can be dropped into any React or Next.js application.

This demo can be used as a reference for how to implement Clerk authentication to persist across different domains using Turborepo, Clerk, Next.js, and React.

Live production examples

Next.js apps

• Root domain
• Satellite domain

React apps

• Root domain
• Satellite domain

Running the example repository

To run the example locally, you need to:

1. Sign up for a Clerk account at https://clerk.com.

2. Go to the Clerk Dashboard and create an application.

3. This example uses Turborepo and pnpm. In the root of the app, run pnpm install to install the required dependencies for all applications.

4. Ensure the allowedRedirectOrigin prop on the root domain's <ClerkProvider/> matches the port your satellite domain is running on.

5. Set the required Clerk environment variables as shown in the .env.example files:

   • Next.js apps: root-domain/.env.example and satellite-domain/.env.example
   • React apps: root-domain/.env.example and satellite-domain/.env.example

6. Running the applications: You can run the applications using the following commands from the root directory:

   • pnpm dev:nextjs - Runs only the Next.js applications (ports 3000 and 3001)
   • pnpm dev:react - Runs only the React applications (ports 3002 and 3003)
   • pnpm dev - Runs all applications (Next.js and React apps) simultaneously

   [!NOTE] Default ports:

   • Next.js root domain: http://localhost:3000
   • Next.js satellite domain: http://localhost:3001
   • React root domain: http://localhost:3002
   • React satellite domain: http://localhost:3003

End-to-End Testing

This repository includes e2e tests using Playwright to verify the multi-domain authentication flows between root and satellite domains.

Test Structure

The e2e tests are organized by framework and include:

• Next.js tests: Located in apps/next.js/root-domain/e2e/
• React tests: Located in apps/react/root-domain/e2e/

Each test suite includes:

• global.setup.ts - Global setup including Clerk authentication configuration
• multidomain.spec.ts - Multi-domain authentication flow tests
• app.spec.ts - Basic application functionality tests

Running Tests

You'll need a test user account and have either username + password or email + password authentication enabled in your Clerk Dashboard. This example is configured to use email and password authentication, but you can modify it to use username and password instead with minor changes to the test files.

Before running e2e tests, ensure you have:

1. Environment variables set for test authentication:

   E2E_CLERK_USER_USERNAME=your-test-user-username
   E2E_CLERK_USER_EMAIL=your-test-user-email
   E2E_CLERK_USER_PASSWORD=your-test-user-password

2. Run tests for specific frameworks:

   # Run Next.js e2e tests only
   pnpm e2e:nextjs
   
   # Run React e2e tests only
   pnpm e2e:react

The tests will automatically:

• Start both root and satellite domain applications
• Run authentication flows across domains
• Verify proper redirection and state persistence
• Test both public and protected routes

Note

The e2e tests use the @clerk/testing package for reliable authentication testing and will create test user sessions as needed. Learn more here.

Troubleshooting

Issue: "Executable doesn't exist" error when running e2e tests

If you encounter an error like:

Error: browserType.launch: Executable doesn't exist at /path/to/playwright/chromium

This means Playwright browser binaries are not installed. Run:

# Install browsers for all e2e test suites
pnpm e2e:install:browsers

This typically happens on fresh installations or after updating Playwright versions.

Learn more

Check out the following resources:

• Satellite domains: Authentication across different domains
• Clerk Documentation
• Next.js Documentation
• Turbo Repos

Found an issue or want to leave feedback

Feel free to create a support thread on our Discord. Our support team will be happy to assist you in the #support channel.

Connect with us

You can discuss ideas, ask questions, and meet others from the community in our Discord.

If you prefer, you can also find support through our Twitter, or you can email us!