This package 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. It is part of the "Ten Minutes to Transactions" effort described in this video.
-
Add as a dependency in your Next.js project
yarn add pi-sdk-nextjs # or npm install pi-sdk-nextjs -
Run the Pi component and API scaffolder:
yarn pi-sdk-nextjs-install
This will generate:
- A
components/PiButton.tsxfile (ready-to-use React component) - All standard Pi payment API endpoints in
app/api/pi_payment/<event>/route.ts(approve,complete,cancel,error,incomplete)
- A
-
Ensure the global Pi SDK is loaded: Add the Pi SDK
<script>to your document head (see the official docs):<script src="https://sdk.minepi.com/pi-sdk.js"></script>
-
Use the PiButton in your UI:
import { PiButton } from '@/components/PiButton'; // or relative: import { PiButton } from '../components/PiButton'; export default function Page() { return <PiButton />; }
-
Register your application with Pi Network: 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 exists, and the development URL to be "http://localhost:3000" (actual port is up to you). Submit your changes.
-
Provide the Pi API key as an environment variable: Click on the "API Key" icon to get the API key for your app.
export PI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -
Register a wallet for your app: Click on the "Wallet" icon to select or create a wallet for use with your app.
-
Run your app through the Sandbox browser: Start the local server.
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.
You can watch a video describing the entire process. Here's are the commands used in the video.
# 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- 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.
- Edit
components/PiButton.tsxand API route files as you wish. New SDK versions won't overwrite unless you delete them first (or add a force flag to the CLI).
- Yes, running multiple times is safe—the CLI checks for pre-existing files and will not overwrite by default.
- Yes, but always audit generated files and integrations before shipping!
- Leverage hooks, server helpers, and the underlying SDKs (
pi-sdk-react,pi-sdk-js) for advanced use cases, custom payment flows, and more.