Next.js Minimal Boilerplate

Översikt

Det minimala Next.js-boilerplate-projektet är en startapp där Dodo Payments redan är anslutet. Lägg till dina API-nycklar och produkt-ID:n så får du en prissida som öppnar checkout, en webhook-endpoint för betalningshändelser och en länk till Customer Portal.

Detta boilerplate använder Next.js 16 App Router med TypeScript, Tailwind CSS 4 och @dodopayments/nextjs-adaptern. Om du vill lägga till samma route handlers i en befintlig app kan du läsa Next.js Adaptor.

Funktioner

Boilerplate-projektet innehåller:

Snabb installation: Gå från klonat repository till en fungerande prissida på cirka fem minuter.
Checkout: Ett förkonfigurerat checkout-flöde byggt på @dodopayments/nextjs.
Prissida: En mörk prissida formgiven med Tailwind CSS.
Webhook-hanterare: En endpoint som verifierar varje webhook-signatur och kör din kod för händelsen.
Customer Portal: En länk i sidhuvudet som öppnar Customer Portal, där kunder hanterar sina prenumerationer.
TypeScript: Typade produktdefinitioner och hanterare.
Förifylld checkout: Skickar kundens namn och e-postadress till checkout så att kunden inte behöver skriva in dem igen.

Förutsättningar

Innan du börjar behöver du:

Node.js 20.9 eller senare, vilket Next.js 16 kräver.
Ett Dodo Payments-konto, för att skapa en API-nyckel och en webhook-signeringhemlighet i dashboarden.

Snabbstart

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Registrera dig hos Dodo Payments och hämta sedan dina inloggningsuppgifter från dashboarden:

API Key: Skapa en nyckel under Dashboard → Developer → API Keys.
Webhook Key: Lägg till en endpoint under Dashboard → Developer → Webhooks och kopiera sedan dess signeringshemlighet. Endpoint-URL:en måste vara offentlig och använda HTTPS. Information om hur du tar emot händelser på din dator finns i Webhook Events.

Skapa båda medan reglaget Live Mode i sidofältet är avstängt. En testlägesnyckel fungerar endast med DODO_PAYMENTS_ENVIRONMENT=test_mode, och betalningar i testläge flyttar inga riktiga pengar.

Configure Environment Variables

Kopiera exempelfilen för att skapa en .env-fil i rotkatalogen:

cp .env.example .env

Ange värdena för dina Dodo Payments-inloggningsuppgifter:

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode

Route handlers läser dessa variabler:

DODO_PAYMENTS_API_KEY autentiserar checkout- och Customer Portal-hanterarna.
DODO_PAYMENTS_WEBHOOK_KEY verifierar webhook-signaturer.
DODO_PAYMENTS_RETURN_URL är platsen dit checkout skickar kunden efter betalningen.
DODO_PAYMENTS_ENVIRONMENT är test_mode eller live_mode.

Lägg inte till din .env-fil i versionshanteringen. Repositoryts .gitignore utesluter den redan.

Add Your Products

Ersätt exempelprodukterna i src/lib/products.ts med dina egna. Ange varje product_id till ID:t för en produkt under Products i din dashboard:

export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];

Prissidan visar name, description, price och features från den här filen. Checkout debiterar det pris som angetts för produkten i Dodo Payments, så håll price synkroniserad med det.

Run the Development Server

npm run dev

Öppna http://localhost:3000 för att se din prissida.

Projektstruktur

Route handlers för checkout, Customer Portal och webhooks finns under src/app/api/:

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

Anpassning

Uppdatera produktinformation

Redigera src/lib/products.ts för att ändra:

Produkt-ID:n, från Products i din Dodo Payments-dashboard
Priser
Funktioner
Beskrivningar

Förifyll kunduppgifter

src/app/components/ProductCard.tsx skickar ett hårdkodat namn och en hårdkodad e-postadress med varje checkout-begäran. Ersätt dem med den inloggade användarens uppgifter:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Uppdatera Customer Portal

Länken Customer Portal i src/app/components/Header.tsx öppnar /api/customer-portal med ett hårdkodat kund-ID. Ersätt det med den inloggade användarens Dodo Payments-kund-ID:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Om du vill hämta ett kund-ID för testning slutför du ett testköp och kopierar sedan kundens ID från Customers i dashboarden. I produktion hämtar du ID:t från din backend.

Webhook-händelser

Hanteraren i src/app/api/webhook/route.ts verifierar varje begäran med DODO_PAYMENTS_WEBHOOK_KEY och hanterar sedan två händelser:

onSubscriptionActive körs när en prenumeration blir aktiv (subscription.active).
onPaymentSucceeded körs när en betalning lyckas (payment.succeeded).

Lägg till din affärslogik i dessa hanterare:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

Om du vill hantera fler händelser lägger du till deras hanterare, till exempel onSubscriptionCancelled. Next.js Adaptor innehåller en lista över alla hanterare som stöds. Dodo Payments kan inte nå localhost. Vid lokal utveckling kan du använda en tunnel, till exempel ngrok, för att exponera din lokala server och använda tunnel-URL:en som din webhook-endpoint.

Driftsättning

Bygg för produktion

npm run build
npm start

Distribuera till Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Lägg till de fyra miljövariablerna i Vercel-dashboarden och ange DODO_PAYMENTS_RETURN_URL till din produktions-URL.

Uppdatera webhook-URL

När du har distribuerat lägger du till din webhook-URL för produktion i Dodo Payments Dashboard, med din domän i stället för example.com:

https://example.com/api/webhook

Varje endpoint har en egen signeringshemlighet. Kopiera den nya endpointens hemlighet till DODO_PAYMENTS_WEBHOOK_KEY i din produktionsmiljö.

Felsökning

Module not found or build errors

Ta bort node_modules och package-lock.json och installera sedan om beroendena:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Kontrollera dessa vanliga orsaker:

Produkt-ID:t finns inte i din Dodo Payments-dashboard.
API-nyckeln eller DODO_PAYMENTS_ENVIRONMENT i .env är fel. En testlägesnyckel fungerar endast med test_mode.

Leta efter felet i webbläsarens konsol och i terminalen där npm run dev körs.

Webhooks not receiving events

Använd ngrok för att exponera din server vid lokal testning:

ngrok http 3000

Lägg till en endpoint med ngroks HTTPS-URL följd av /api/webhook i din Dodo-dashboard. Kopiera den endpointens signeringshemlighet till DODO_PAYMENTS_WEBHOOK_KEY i din .env-fil.

Customer portal link doesn't work

Ersätt det hårdkodade CUSTOMER_ID i src/app/components/Header.tsx med ID:t för en kund i din Dodo Payments-dashboard.I produktion hämtar du i stället kund-ID:t från ditt autentiseringssystem och din databas.

Läs mer

Dodo Payments Documentation
Checkout Sessions Documentation
Webhooks Documentation
Next.js Adaptor: alternativ för hanterarna Checkout, CustomerPortal och Webhooks

Support

Om du behöver hjälp med boilerplate-projektet:

Ställ frågor i Discord-communityt.
Rapportera problem och följ uppdateringar i GitHub-repositoryt.
Mejla supportteamet.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Översikt

Funktioner

Förutsättningar

Snabbstart

Projektstruktur

Anpassning

Uppdatera produktinformation

Förifyll kunduppgifter

Uppdatera Customer Portal

Webhook-händelser

Driftsättning

Bygg för produktion

Distribuera till Vercel

Uppdatera webhook-URL

Felsökning

Läs mer

Support

​Översikt

​Funktioner

​Förutsättningar

​Snabbstart

​Projektstruktur

​Anpassning

​Uppdatera produktinformation

​Förifyll kunduppgifter

​Uppdatera Customer Portal

​Webhook-händelser

​Driftsättning

​Bygg för produktion

​Distribuera till Vercel

​Uppdatera webhook-URL

​Felsökning

​Läs mer

​Support

Översikt

Funktioner

Förutsättningar

Snabbstart

Projektstruktur

Anpassning

Uppdatera produktinformation

Förifyll kunduppgifter

Uppdatera Customer Portal

Webhook-händelser

Driftsättning

Bygg för produktion

Distribuera till Vercel

Uppdatera webhook-URL

Felsökning

Läs mer

Support