Skip to main content

Getting Started

This guide will walk you through setting up your development environment and building your first Watchee Mini App.

Prerequisites​

  • Node.js 18+
  • npm or yarn or pnpm
  • A text editor (VS Code recommended)

Installation​

To start a new project, we recommend using our starter template.

npx create-next-app -e https://github.com/watchee-tv/minikit-template my-mini-app
cd my-mini-app
npm install

Or, if you want to add MiniKit to an existing project:

npm install watchee-minikit

Explore the Template​

The starter template (minikit-template) is a comprehensive example of all SDK features. It uses Next.js 15 (App Router) and React 19 to provide a modern foundation.

It includes demos for:

  • Authentication (src/app/demos/auth/): Connecting wallets and signing messages.
  • Payments (src/app/demos/payment/): Requesting APT/token payments.
  • Transactions (src/app/demos/transaction/): Signing and submitting transactions.
  • User Data (src/app/demos/user/): Fetching profiles and NFTs.
  • Content & Social (src/app/demos/content/): Publishing and sharing content.
  • Device Features (src/app/demos/device/): Haptic feedback and notifications.
  • Camera & Media (src/app/demos/media/): Camera and microphone access via WebRTC.

We recommend exploring these files to understand the best practices for using the MiniKit SDK.

Usage​

The MiniKit SDK is designed to be used on the client-side.

1. Import the SDK​

import { minikit } from 'watchee-minikit';

2. Check for Availability​

Before calling any methods, ensure the SDK is running within the Watchee environment (though the SDK handles this check gracefully in most cases).

useEffect(() => {
  // Optional: Check if window.WatcheeSDK is defined
  console.log('MiniKit ready');
}, []);

3. Example: Connect Wallet​

async function handleConnect() {
  try {
    const account = await minikit.walletAuth();
    console.log('Connected address:', account.address);
  } catch (error) {
    console.error('Connection failed:', error);
  }
}

Testing your Mini App​

To test your Mini App, you can run it locally in your browser. However, SDK methods that rely on the native bridge (like walletAuth) will fail outside the Watchee app.

Local Testing​

Since the mobile app cannot access localhost on your computer directly, you need to expose your local server via a tunnel. We recommend using ngrok, zrok, or tunnelmole.

  1. Start your local development server:

    npm run dev

  2. Start a tunnel (e.g., using ngrok):

    ngrok http 3000

  3. Use the generated URL (e.g., https://your-tunnel.ngrok-free.app) to load your Mini App within Watchee.

Mobile Debugging​

Debugging on a mobile device can be challenging. We recommend using Eruda, a console for mobile browsers.

The minikit-template comes with Eruda pre-configured. It provides an on-screen console overlay that allows you to:

  • View console logs, errors, and network requests.
  • Inspect DOM elements and styles.
  • Execute JavaScript commands.

To enable it, ensure you are using the ErudaProvider in your app layout (already set up in the template).

Next Steps​