In an era where online interactions are often plagued by bots and automated spam, World ID offers a cutting-edge solution for verifying real human identities while safeguarding user privacy. By leveraging cryptographic proof-of-personhood, World ID ensures that only genuine users can access your application without revealing their personal data.
Setting up a World Mini App is one way to integrate Sign in with World ID into your application, specifically within the World App ecosystem. Mini apps enable third-party developers to create native-like applications within World App. Building a mini app will provide access to World App’s rapidly growing user network and monetization opportunities via WLD and USDC. In addition, mini apps introduce smart contract support natively inside of World App.
In this guide, I will walk you through the process of starting a brand- new World Mini App project from scratch. Using the official React template, we will simplify the setup and deployment process. I will also provide essential resources to support your ongoing development.
Prerequisites
Before you begin, ensure you have:
- A World ID Developer Account (Login | Developer Portal)
- Node.js and pnpm installed
- Ngrok and Nginx installed (for local development)
Getting started with World Mini App from scratch
Step 1: Clone the react template
The World Mini App official template simplifies development. Clone the repository:
git clone https://github.com/worldcoin/minikit-react-template.git
cd minikit-react-template
Step 2: Create a team and app in the world developer portal
- Go to World Developer Portal.
- Create a new team.
- Create a new app within your team.
- Navigate to the Sign in with World ID tab inside your app settings.
- Copy the Client ID and Secret.
- Get your API key from the team settings.
Step 3: Configure environment variables
The .env.example file in the template (both frontend and backend directories) provides a guide for environment variables. Copy and update it with your credentials:
cp .env.example .env
Then, update the .env files in both the frontend and backend folders with:
- Client ID and Secret from the app settings.
- API key from the team settings.
Step 4: Install dependencies
Navigate to the project root and install dependencies for both frontend and backend:
cd frontend; pnpm i; cd -;
cd backend; pnpm i;
Step 5: Create a ‘test-action’ in the developer portal
The frontend is configured to invoke a ‘test-action’ (check frontend/src/components/Verify/index.tsx) for user verification. This ‘test-action’ needs to be created in the World Developer Portal.
- Go to the ‘Incognito actions’ tab inside your app settings.
- Click ‘New action’.
- Specify the maximum number of verifications per user along with other details.
- Save the action.
Step 6: Set up Nginx for local development
To expose your local application through one Ngrok tunnel, set up Nginx as a reverse proxy.
- Use the provided Nginx configuration (found in the root of the repo).
- Start Nginx with:
sudo nginx -c full/path/to/this/repo/nginx.conf
Or if running from the root directory:
sudo nginx -c $(pwd)/nginx.conf
To stop Nginx, run:
sudo nginx -s stop
Step 7: Expose localhost using Ngrok
Start an Ngrok tunnel:
ngrok http 8080
The port doesn’t matter, make sure it’s the listen one from nginx config.
Copy the public URL displayed in the terminal.
Step 8: Update your app URL in the world developer portal
- Go back to the World Developer Portal.
- Open your app settings.
- Update the app URL with the Ngrok public URL.
- Save changes.
Step 9: Run and test the app
Once everything is set up, start the application and test it:
- Start the frontend and backend using:
pnpm run dev
Scan the QR Code displayed in the developer portal from your smartphone.
The app will open inside the World App, and you can now try Sign in with World ID functionality.
Additional resources
To further enhance your World Mini App and explore more possibilities, check out these resources:
- https://docs.world.org/mini-apps – Learn more about World Mini App Development.
- Minikit React Template Repository – Official React template for building mini apps.
- https://discord.com/invite/worldnetwork – Connect with other developers and get support.
Conclusion
You have successfully set up and run a World Mini App using the official template. This guide covered configuring World Dev Portal, setting up Nginx and Ngrok, and integrating Sign in with World ID. Now, you can extend the mini app to suit your use case.
