Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
minikit
✓ import { minikit } from 'better-auth-minikit'
✗ const { minikit } = require('better-auth-minikit')
This is the server-side plugin for `better-auth` and should be imported using ESM syntax.
minikitClient
✓ import { minikitClient } from 'better-auth-minikit/client'
✗ import { minikitClient } from 'better-auth-minikit'
The client-side plugin has a distinct entry point at `better-auth-minikit/client`.
AuthClientMinikit
✓ type AuthClientMinikit = ClientPlugin<typeof minikitClient>
This is a TypeScript type for the client-side plugin's methods, useful for type inference and explicit typing, though often inferred by `createAuthClient`.
This quickstart demonstrates both the server-side configuration of the `minikit` plugin for `better-auth` and the client-side setup and usage with `minikitClient`, covering nonce retrieval, SIWE message signing with Worldcoin Minikit, and final sign-in verification.
import { betterAuth } from "better-auth";
import { minikit } from "better-auth-minikit";
import { generateRandomString } from "better-auth/crypto";
import { parseSiweMessage, validateSiweMessage } from "viem/siwe";
import { createAuthClient } from "better-auth/react";
import { minikitClient } from "better-auth-minikit/client";
import { MiniKit } from '@worldcoin/minikit-js';
import { createSiweMessage } from 'viem/siwe'; // Helper to create SIWE messages
// --- Server Setup (Node.js/Edge Function) ---
export const auth = betterAuth({
plugins: [
minikit({
domain: "app.example.com", // Replace with your actual domain
getNonce: async () => {
return generateRandomString(32);
},
verifyMessage: async ({ message, signature, address, chainId }) => {
try {
const parsedMessage = await parseSiweMessage(message);
const valid = await validateSiweMessage({
message,
signature,
domain: "app.example.com",
nonce: parsedMessage.nonce,
address: address, // Ensure address is passed for robust validation
chainId: chainId // Ensure chainId is passed for robust validation
});
return valid;
} catch (e) {
console.error("SIWE message verification failed:", e);
return false;
}
}
})
]
});
// --- Client Setup (React Component or similar) ---
const client = createAuthClient({
plugins: [minikitClient()],
fetchOptions: {
credentials: "include", // Essential for session cookies in MiniApps
},
});
export const authClient = client;
// --- Client-side Usage Example (within an async function) ---
async function authenticateWithWorldcoin() {
const walletAddress = "0x..."; // User's actual wallet address from Minikit
const chainId = 1; // Example: Ethereum Mainnet
// 1. Get Nonce
const { data: nonceData, error: nonceError } = await authClient.minikit.getNonce({
walletAddress,
chainId
});
if (nonceError || !nonceData?.nonce) {
console.error("Failed to get nonce:", nonceError);
return;
}
const nonce = nonceData.nonce;
// 2. Sign Message (using Worldcoin Minikit SDK)
const message = createSiweMessage({
domain: window.location.host,
address: walletAddress,
statement: "Sign in to My App",
uri: window.location.origin,
version: "1",
chainId: chainId,
nonce: nonce,
});
let signature;
try {
// This part requires Worldcoin Minikit to be initialized and available
const { commandPayload } = await MiniKit.commands.signMessage({
message: message
});
signature = commandPayload;
} catch (signError) {
console.error("Failed to sign message with Minikit:", signError);
return;
}
// 3. Verify and Sign In
const { data: signInData, error: signInError } = await authClient.minikit.signInWithMinikit({
message,
signature,
walletAddress,
chainId,
user: {
username: "worldcoin-user",
profilePictureUrl: "https://example.com/default.png"
}
});
if (signInData?.success) {
console.log("Successfully signed in user:", signInData.user);
} else {
console.error("Sign-in failed:", signInError);
}
}
// Call the function to initiate authentication (example)
// authenticateWithWorldcoin();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'minikit')
The `minikitClient` plugin was not correctly registered with `createAuthClient`.
fixEnsure `minikitClient()` is included in the `plugins` array when calling `createAuthClient({ plugins: [minikitClient()] })`. Failed to get nonce: { message: 'Unauthorized', status: 401 }
The server-side `betterAuth` instance with the `minikit` plugin is not correctly initialized or accessible, or there's an issue with your `better-auth` setup.
fixVerify your server's `betterAuth` configuration, ensure the `minikit` plugin is added, and check that the endpoint receiving the `getNonce` request is correctly routed and uses the `betterAuth` instance.
SIWE message verification failed: Error: Nonce mismatch
The nonce generated by the server does not match the nonce included in the SIWE message signed by the client, or the server's `getNonce` and `verifyMessage` implementations are inconsistent.
fixDouble-check the `getNonce` implementation to ensure it returns a unique, random string and that this exact nonce is passed to `createSiweMessage` on the client and then used by `validateSiweMessage` on the server.
SIWE message verification failed: Error: Domain mismatch
The domain specified in the SIWE message signed by the client does not match the `domain` configured in the server-side `minikit` plugin.
fixEnsure the `domain` property provided to `minikit({ domain: '...' })` on the server is identical to the `domain` parameter used when creating the SIWE message on the client side. Audit
Dependencies
better-authrequiredPeer dependency, this package is a plugin for better-auth.
viemoptionalRecommended for SIWE message parsing and validation in the server-side setup.
@worldcoin/minikit-jsoptionalRequired on the client-side for signing SIWE messages with Worldcoin Minikit.