Skip to main content

Pi SDK Next.js

This package, pi-sdk-nextjs, helps you quickly scaffold, configure, and integrate all necessary components for using Pi Network payments, authentication, and user flows with a Next.js project. It is designed for modern Next.js apps (App Router or Pages Router) that want a working, idiomatic Pi payment and authentication experience with minimal boilerplate.

This guide demonstrates how to integrate the Pi SDK into a Next.js app. This example shows how to initialize the Pi SDK, authenticate a Pioneer, and create a payment request inside a Pi app.

The pi-sdk-nextjs package is part of the “Ten Minutes to Transactions” effort described in this video.

If you, or your GenAI agent, are planning to use the Next.js for your app, it is highly suggested that you use this package rather than implement transaction processing by hand with the core Pi SDK. The three way handshake between client, server, and the Pi servers required is provded for you.

Note: Pi SDK authentication and payment features require the application to run inside the Pi Browser.

Next.js Quick Start​

Register your application with Pi Network​

While this process is covered in the Getting Started Guide, here is a brief reminder of the steps you need to take. Application registration is also discussed in the video.

  • Open your Pi Mining app.
  • Click the hamburger (☰).
  • Select “Pi Utilities”.
  • Click the “Develop” icon followed by the “New App” icon.
  • Provide name and description of your app and submit.
  • Then click the “Configuration” icon.
  • Set the app URL to something valid, but does not necessarily exist.
  • Set the development URL to be http://localhost:3000. The actual port is between you and your development server.
  • Submit your changes.
  • Get your API key.
  • Register a wallet for your app.

Add pi-sdk-nextjs as a dependency in your Next.js project​

NPM

Yarn

npm install pi-sdk-nextjs
yarn add pi-sdk-nextjs

This step, and the following ones, can be seen in the video.

Run the Pi component and API scaffolder​

NPM

Yarn

npx pi-sdk-nextjs-install
yarn pi-sdk-nextjs-install

This will generate:

  • A components/PiButton.tsx file (ready-to-use React component)
  • All standard Pi payment API endpoints in app/api/pi_payment/<event>/route.ts (approve, complete, cancel, error, incomplete)

Ensure the global Pi SDK is available​

Add in your main app HTML (e.g., public/index.html or via a Script/Head component).

HTML

<head>
  <!-- ... other <head> content (meta, title, styles, etc.) ... -->
  <script src="https://sdk.minepi.com/pi-sdk.js"></script>
</head>

This is required for all Pi SDK browser integrations.

Add a PiButton to your UI​

TypeScript

import { PiButton } from '@/components/PiButton';
// or relative:
import { PiButton } from '../components/PiButton';

export default function Page() {
  return <PiButton />;
}

Let your app know your API key​

Bash

export PI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Run your app through the Sandbox browser​

Start the local server.

NPM

Yarn

npm dev
yarn dev

Visit https://sandbox.minepi.com/mobile-app-ui/app/your-app-name. It will ask you to provide an authorization code to the Pi Mining app. Click the link at the bottom of the Pi Utilities screen.

Video Script​

You can watch a video describing the entire process, or just setting up Next.js. Here are the commands used in the video.

Bash

# Create the app
yarn create next-app tmtt_nextjs --yes

cd tmtt_nextjs

# Add the Pi SDK package for Next.js
yarn add pi-sdk-nextjs@https://github.com/pi-apps/pi-sdk-nextjs

# Generate the routes and PiButton.tsx
yarn pi-sdk-nextjs-install

# Load Pi SDK on your pages
sed -i '' '3i\\
import Script from "next/script";\\
'  app/layout.tsx

sed -i '' '28i\\
        <head>\\
          <Script src="https://sdk.minepi.com/pi-sdk.js" strategy="beforeInteractive" />\\
        </head>\\
' app/layout.tsx

# Enable PiButton on the home page
sed -i '' '2i\\
import { PiButton } from "@/components/PiButton";
' app/page.tsx

sed -i '' '38i\\
   <PiButton/>
' app/page.tsx

# Build the app
yarn build

FAQ​

What does pi-sdk-nextjs-install actually do?​

  • Generates a PiButton component for direct use in your app.
  • Generates stubbed (or pluggable) Next.js API routes for all standard Pi payment lifecycle events.
  • Handles directory creation and required use client directives for new components.

How do I customize the generated code?​

  • Edit components/PiButton.tsx and API route files as you wish. New SDK versions won’t overwrite unless you delete them first (or add a force flag to the installation script).

Can I run pi-sdk-nextjs-install many times?​

  • Yes, running the script multiple times is safe, as it checks for pre-existing files and will not overwrite by default.

Is this production safe?​

  • Yes, but always audit generated files and integrations before shipping!

What else can I do with the SDKs?​

  • Leverage hooks, server helpers, and the underlying SDKs (pi-sdk-react, pi-sdk-js) for advanced use cases, custom payment flows, and more.