flowglad-setup

<!-- @flowglad/skill sources_reviewed: 2026-02-24T21:27:00Z source_files: - platform/docs/quickstart.mdx - platform/docs/sdks/setup.mdx - platform/docs/sdks/introduction.mdx - platform/docs/sdks/nextjs.mdx - platform/docs/sdks/server.mdx - platform/docs/snippets/setup-nextjs.mdx - platform/docs/snippets/setup-react.mdx - platform/docs/snippets/setup-server.mdx -->

Flowglad Setup

Abstract

This skill covers installing and configuring the Flowglad SDK for Next.js, Express, and React applications. It includes framework detection, package installation, environment setup, server factory creation, route handler setup, and provider configuration.

---

Table of Contents

1. Framework Detection — CRITICAL
   • 1.1 Detecting the Framework
2. Next.js Setup — CRITICAL
   • 2.1 Package Installation
   • 2.2 Environment Variables
   • 2.3 Server Factory Creation
   • 2.4 API Route Handler
   • 2.5 FlowgladProvider Setup
3. Express Setup — HIGH
   • 3.1 Package Installation
   • 3.2 Server Factory Creation
   • 3.3 Express Router Setup
4. React Setup (Other Frameworks) — HIGH
   • 4.1 Package Installation
   • 4.2 FlowgladProvider Setup
   • 4.3 Backend Requirements
5. Customer ID Mapping — CRITICAL
   • 5.1 Using Your App's User ID
   • 5.2 Organization vs User Customers
6. getCustomerDetails Callback — HIGH
   • 6.1 Required Fields
   • 6.2 Database Integration

---

1. Framework Detection

Impact: CRITICAL

Before beginning setup, detect which framework the user is using to ensure correct package installation and configuration.

1.1 Detecting the Framework

Impact: CRITICAL (incorrect detection leads to wrong SDK usage)

Check for framework-specific configuration files to determine the correct setup path.

Detection Rules:

Next.js:     next.config.js OR next.config.ts OR next.config.mjs exists
Express:     "express" in package.json dependencies
React (CRA): "react-scripts" in package.json dependencies
Vite React:  "vite" in package.json devDependencies AND "react" in dependencies

Incorrect: assuming Next.js without checking

// Don't assume the framework - always verify first
import { FlowgladServer } from '@flowglad/nextjs/server'
// This will fail if the user is using Express or plain React

Correct: check framework before recommending packages

# Check for Next.js
ls next.config.* 2>/dev/null && echo "Next.js detected"

# Check for Express (in package.json)
grep -q '"express"' package.json && echo "Express detected"

After detection, proceed to the appropriate setup section.

---

2. Next.js Setup

Impact: CRITICAL

Next.js is the primary supported framework with the most streamlined integration.

2.1 Package Installation

Impact: CRITICAL (wrong packages = broken integration)

Incorrect: installing individual packages separately

# Don't install packages piecemeal
npm install @flowglad/server
npm install @flowglad/react
# Missing the unified Next.js package

Correct: install the Next.js package (includes server and react)

bun add @flowglad/nextjs @flowglad/react

The @flowglad/nextjs package re-exports server functionality and is designed for Next.js App Router.

2.2 Environment Variables

Impact: CRITICAL (missing env vars = authentication failures)

Incorrect: hardcoding API key

// SECURITY RISK: Never hardcode secrets
const flowglad = new FlowgladServer({
  apiKey: 'sk_live_abc123...',
  // ...
})

Correct: use environment variable

# .env.local
FLOWGLAD_SECRET_KEY=sk_live_your_secret_key_here

// The SDK automatically reads FLOWGLAD_SECRET_KEY from process.env
// No need to pass apiKey explicitly
const flowglad = new FlowgladServer({
  customerExternalId,
  getCustomerDetails,
})

The SDK automatically reads FLOWGLAD_SECRET_KEY from the environment. You only need to pass apiKey explicitly if using a different environment variable name.

2.3 Server Factory Creation

Impact: CRITICAL (incorrect factory = broken billing operations)

Create a factory function that returns a FlowgladServer instance scoped to a specific customer.

Incorrect: creating a single shared instance

// lib/flowglad.ts
// BAD: Single shared instance loses customer context
export const flowglad = new FlowgladServer({
  // No customerExternalId - will fail for customer-specific operations
})

Correct: factory function that creates scoped instances

// lib/flowglad.ts
import { FlowgladServer } from '@flowglad/nextjs/server'
import { db } from '@/db'

export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (externalId: string) => {
      const user = await db.users.findUnique({
        where: { id: externalId },
      })
      if (!user) {
        throw new Error(`User not found: ${externalId}`)
      }
      return {
        email: user.email,
        name: user.name || user.email,
      }
    },
  })
}

The factory pattern ensures each request gets a properly scoped server instance.

2.4 API Route Handler

Impact: CRITICAL (missing route = SDK cannot communicate with Flowglad)

Create a catch-all API route to handle Flowglad SDK requests from the frontend.

Incorrect: manual route implementation

// app/api/flowglad/route.ts
// BAD: Manual implementation misses many endpoints
export async function POST(req: Request) {
  const body = await req.json()
  // Incomplete - missing proper routing, validation, etc.
  return Response.json({ error: 'Not implemented' })
}

Correct: use nextRouteHandler with catch-all route

// app/api/flowglad/[...path]/route.ts
import { nextRouteHandler } from '@flowglad/nextjs/server'
import { auth } from '@/lib/auth' // Your auth solution
import { flowglad } from '@/lib/flowglad'

export const { GET, POST } = nextRouteHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    // Extract the authenticated user's ID from your auth system
    const session = await auth()
    if (!session?.user?.id) {
      throw new Error('Unauthorized')
    }
    return session.user.id
  },
})

Important: The route must be a catch-all ([...path]) to handle all Flowglad API subroutes.

2.5 FlowgladProvider Setup

Impact: CRITICAL (missing provider = hooks don't work)

Wrap your application with FlowgladProvider to enable the useBilling hook.

Incorrect: not wrapping the app

// app/layout.tsx
// BAD: useBilling will throw without FlowgladProvider
export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

Correct: wrap with FlowgladProvider

// app/layout.tsx
import { FlowgladProvider } from '@flowglad/react'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <FlowgladProvider>{children}</FlowgladProvider>
      </body>
    </html>
  )
}

For apps with a custom API base URL:

<FlowgladProvider baseURL="https://api.yourapp.com">
  {children}
</FlowgladProvider>

---

3. Express Setup

Impact: HIGH

For Express applications, use the @flowglad/server package with the Express router helper.

3.1 Package Installation

Impact: HIGH (wrong package = missing Express utilities)

Incorrect: installing the Next.js package for Express

# Wrong package for Express
npm install @flowglad/nextjs

Correct: install the server package

bun add @flowglad/server

3.2 Server Factory Creation

Impact: HIGH (same pattern as Next.js)

Incorrect: not providing getCustomerDetails

// utils/flowglad.ts
// BAD: Missing getCustomerDetails - customer creation will fail
export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    // getCustomerDetails is required!
  })
}

Correct: provide complete factory

// utils/flowglad.ts
import { FlowgladServer } from '@flowglad/server'
import { db } from '../db'

export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (externalId: string) => {
      const user = await db.users.findOne({ id: externalId })
      if (!user) {
        throw new Error(`User not found: ${externalId}`)
      }
      return {
        email: user.email,
        name: user.name,
      }
    },
  })
}

3.3 Express Router Setup

Impact: HIGH (incorrect setup = broken API routes)

Incorrect: manually handling each route

// routes/flowglad.ts
// BAD: Manual route handling is error-prone and incomplete
import express from 'express'

const router = express.Router()

router.post('/checkout', async (req, res) => {
  // Manual implementation - missing validation, error handling, etc.
})

export { router }

Correct: use expressRouter helper

// routes/flowglad.ts
import { expressRouter } from '@flowglad/server/express'
import type { Request } from 'express'
import { flowglad } from '../utils/flowglad'

export const flowgladRouter = expr

---

*Content truncated.*