Mini App Development Guide
Build apps for World App using the MiniKit-JS SDK
1. Mini App Development Overview
Mini Apps are web applications that run inside World App. Using the MiniKit-JS SDK, you can integrate with World App's native UI, World ID verification, and payment features.
What You Can Do
World ID Verification
Verify if a user is an Orb-verified human
USDC Payments
Stablecoin payments on World Chain
User Info Retrieval
Get wallet addresses, usernames, etc.
Native UI Integration
Leverage World App's native features
Tech Stack
- • Frontend: React, Next.js, Vue.js, Vanilla JS
- • SDK: @worldcoin/minikit-js, @worldcoin/minikit-react
- • UI Kit: mini-apps-ui-kit-react (optional)
- • Blockchain: World Chain (Optimism L2)
2. MiniKit-JS Setup
Installation
# npm
npm install @worldcoin/minikit-js
# For React (optional)
npm install @worldcoin/minikit-react
# UI Kit (optional)
npm install @worldcoin/mini-apps-ui-kit-reactReact/Next.js Initialization
components/MiniKitProvider.tsx
"use client";
import { MiniKit } from "@worldcoin/minikit-js";
import { useEffect, ReactNode } from "react";
export function MiniKitProvider({ children }: { children: ReactNode }) {
useEffect(() => {
MiniKit.install();
}, []);
return <>{children}</>;
}app/layout.tsx
import { MiniKitProvider } from "@/components/MiniKitProvider";
export default function RootLayout({ children }) {
return (
<html>
<body>
<MiniKitProvider>
{children}
</MiniKitProvider>
</body>
</html>
);
}Detecting Mini App Environment
import { MiniKit } from "@worldcoin/minikit-js";
// Check if running inside World App
if (MiniKit.isInstalled()) {
console.log("Running inside World App");
} else {
console.log("Running in browser");
}3. Implementing World ID Verification
With MiniKit, you can easily verify if a user is an Orb-verified human.
Implementation
import { MiniKit, VerificationLevel } from "@worldcoin/minikit-js";
async function verifyUser() {
if (!MiniKit.isInstalled()) {
return { success: false, error: "World App required" };
}
try {
const result = await MiniKit.commandsAsync.verify({
action: "your-app-action-id", // Set in Developer Portal
verification_level: VerificationLevel.Orb, // Require Orb verification
});
if (result.finalPayload.status === "success") {
// Verify on backend
const response = await fetch("/api/verify", {
method: "POST",
body: JSON.stringify(result.finalPayload),
});
return { success: true, data: await response.json() };
}
} catch (error) {
return { success: false, error };
}
}Verification Levels
VerificationLevel.Orb
Only Orb-verified users allowed. Highest security level.
VerificationLevel.Device
Device verification level. More users can access.
Important
Always verify results on the backend. Frontend-only verification is not secure.
4. Implementing USDC Payments
With MiniKit, you can easily implement USDC payments on World Chain. Offer payment experiences without wallet connections and zero fees.
Implementation
import { MiniKit, Tokens, tokenToDecimals } from "@worldcoin/minikit-js";
async function initiatePayment(amount: number, reference: string) {
if (!MiniKit.isInstalled()) {
return { success: false, error: "World App required" };
}
try {
const result = await MiniKit.commandsAsync.pay({
reference, // Order ID, etc.
to: "0xYourWalletAddress", // Recipient address
tokens: [
{
symbol: Tokens.USDCE, // USDC
token_amount: tokenToDecimals(amount, Tokens.USDCE).toString(),
},
],
description: "Product purchase",
});
if (result.finalPayload.status === "success") {
// Payment successful
return {
success: true,
transactionId: result.finalPayload.transaction_id
};
}
} catch (error) {
return { success: false, error };
}
}Supported Tokens
- • Tokens.USDCE: USDC (stablecoin)
- • Tokens.WLD: WLD token
Benefits
- ✅ No wallet connection needed - just tap
- ✅ Zero gas fees - transactions on World Chain
- ✅ Instant payments - completes in seconds
- ✅ No middlemen - direct transfers
5. Testing and Debugging
Local Development
Expose Local with NGROK
ngrok http 3000Get a public URL with NGROK to make it accessible from World App
Configure in Developer Portal
Set App URL to NGROK URL in Developer Portal
Test in World App
Open your Mini App directly from World App on a real device
Debugging Tips
- • Use console.log to check SDK responses
- • Detect World App environment with MiniKit.isInstalled()
- • Implement browser fallback behavior
- • Implement thorough error handling
6. Resources and Documentation
Official Documentation
docs.world.org/mini-apps - Latest API specs and guides
GitHub - MiniKit-JS
SDK source code and examples
Developer Portal
App registration, Action ID, settings
npm - @worldcoin/minikit-js
Package info and version history
Template Repositories
- • React template (with backend)
- • Vanilla JS template
- • Next.js template
Available from the worldcoin/minikit-js GitHub repository
Get bonus WLD with this invite code
Use this invite code to receive additional WLD.
Get World App6YQ47NH