Next.js Quickstart

This guide builds the Quickstart flow into a Next.js app with the BundleUp JavaScript SDK. A user clicks Connect GitHub, authorizes on GitHub, and lands back in your app, which exchanges the one-time code for a connection_id and lists their repositories through the Unified API.

Prerequisites

Node.js 18+ installed.
In the BundleUp dashboard, complete steps 1 to 3 of the Quickstart:
- a GitHub integration with the identifier github,
- http://localhost:3000/callback registered under Auth → Redirect URIs,
- an API key, and your Client ID from the Auth page.

Step 1: Create a new Next.js app

If you don’t already have a Next.js project, start by creating one. BundleUp works with both the App Router and Pages Router, but this guide uses the App Router. Run one of the following commands to scaffold a new app:

npm create next-app@latest bundleup-nextjs -- --yes
cd bundleup-nextjs
npm install

pnpm create next-app bundleup-nextjs --yes
cd bundleup-nextjs
pnpm install

yarn create next-app bundleup-nextjs --yes
cd bundleup-nextjs
yarn install

bunx create-next-app bundleup-nextjs --yes
cd bundleup-nextjs
bun install

Once finished, you should have a working Next.js app you can run locally.

Step 2: Install `@bundleup/sdk`

Next, install the official BundleUp SDK. This SDK is used server-side to make authenticated requests to third-party APIs using a connection_id.

npm install @bundleup/sdk

pnpm add @bundleup/sdk

yarn add @bundleup/sdk

bun add @bundleup/sdk

You’ll use this SDK later to fetch data from GitHub through the BundleUp Unified API.

Step 3: Configure environment variables

BundleUp uses two types of credentials:

A server-side API key for making API requests
A client-safe Client ID for starting the authorization flow

Create a .env.local file in your project root and add the following:

.env.local

# Server-side only - NEVER expose this in the browser
BUNDLEUP_API_KEY=your_api_key_here

# Client-side safe - used in browser for auth redirect
NEXT_PUBLIC_BUNDLEUP_CLIENT_ID=your_client_id_here
NEXT_PUBLIC_BUNDLEUP_INTEGRATION_ID=github

# Must exactly match a redirect URI registered in your BundleUp dashboard
NEXT_PUBLIC_BUNDLEUP_REDIRECT_URI=http://localhost:3000/callback

Your API key must remain server-side only. Never expose it in client-side code or environment variables prefixed with NEXT_PUBLIC_.

Step 4: Create the authorization link

In this step, you’ll create a simple page that sends the user to BundleUp’s authorization endpoint. This URL:

Identifies your app (client_id)
Specifies which integration to connect (integration_id)
Defines where the user should be redirected after authorization (redirect_uri)

app/page.tsx

import { BundleUp } from "@bundleup/sdk";

const client = new BundleUp(process.env.BUNDLEUP_API_KEY!);

export default function Home() {
  const url = client.auth.buildAuthorizationUrl({
    clientId: process.env.NEXT_PUBLIC_BUNDLEUP_CLIENT_ID!,
    integrationId: process.env.NEXT_PUBLIC_BUNDLEUP_INTEGRATION_ID!,
    redirectUri: process.env.NEXT_PUBLIC_BUNDLEUP_REDIRECT_URI!,
  });

  return (
    <div className="flex items-center justify-center p-4">
      <a
        href={url}
        className="bg-blue-500 hover:bg-blue-600 text-white px-6 py-3 rounded-lg font-medium"
      >
        Connect GitHub
      </a>
    </div>
  );
}

When a user clicks Connect GitHub, they’ll be redirected to GitHub to approve access.

Step 5: Handle the callback and fetch data

After the user authorizes the integration, BundleUp redirects them back to your app with a one-time code. The code is not the connection. Your server exchanges it, using your API key, for a connection_id. The code expires after 5 minutes and can only be used once. The connection_id represents:

A specific user
A specific integration
Securely stored credentials managed by BundleUp

The connection_id is stable and reusable. You should store it and reuse it for future requests instead of re-authorizing the user. Create a callback page (for example, app/callback/page.tsx), exchange the code, and use the SDK to fetch data:

app/callback/page.tsx

import { BundleUp } from "@bundleup/sdk";

const client = new BundleUp(process.env.BUNDLEUP_API_KEY!);

interface PageProps {
  searchParams: Promise<{
    code?: string;
    error?: string;
    error_description?: string;
  }>;
}

export default async function Callback({ searchParams }: PageProps) {
  const { code, error, error_description } = await searchParams;

  if (error || !code) {
    return (
      <div className="flex items-center justify-center p-4">
        <p className="text-red-600">Error: {error_description ?? "Missing code"}</p>
      </div>
    );
  }

  // Exchange the one-time code for the connection (server-side only)
  const { connection_id } = await client.auth.getConnectionFromCode({
    code,
    redirectUri: process.env.NEXT_PUBLIC_BUNDLEUP_REDIRECT_URI!,
  });

  const repos = await client.unify(connection_id).git.repos();

  return (
    <div className="flex items-center justify-center p-4">
      <p className="text-green-600">
        Successfully connected! Here are your repos:
      </p>
      <ul>
        {repos.data.map((repo) => (
          <li key={repo.id}>{repo.full_name}</li>
        ))}
      </ul>
    </div>
  );
}

redirectUri must be exactly the same value you used to start the flow. BundleUp rejects the exchange otherwise.

At this point:

BundleUp handles authentication, token refresh, and API differences
You make a single, normalized API call

Step 6: Run your application

Start your Next.js development server:

npm run dev

Visit http://localhost:3000 and click “Connect GitHub”. You’ll be redirected to GitHub to authorize the connection. After authorization, you’ll be redirected back and can fetch your repositories.

Next steps

Store the connection_id against the signed-in user in your database, and reuse it. Don’t send the user through the flow again.
Pass a state value when you build the authorization URL and check it in the callback, to protect against CSRF. See Connecting user accounts.
Pass an external_id (your user ID) so you can find connections by user later.
Call the provider directly through the Proxy when you need something the Unified API doesn’t cover.
See the full JavaScript SDK reference.

Get started

Concepts

Authentication

Integrations

Proxy

Unified API

MCP

Webhooks

Operations

Platform

Next.js Quickstart

Prerequisites

Step 1: Create a new Next.js app

Step 2: Install `@bundleup/sdk`

Step 3: Configure environment variables

Step 4: Create the authorization link

Step 5: Handle the callback and fetch data

Step 6: Run your application

Next steps

​Prerequisites

​Step 1: Create a new Next.js app

​Step 2: Install @bundleup/sdk

​Step 3: Configure environment variables

​Step 4: Create the authorization link

​Step 5: Handle the callback and fetch data

​Step 6: Run your application

​Next steps

Prerequisites

Step 1: Create a new Next.js app

Step 2: Install `@bundleup/sdk`

Step 3: Configure environment variables

Step 4: Create the authorization link

Step 5: Handle the callback and fetch data

Step 6: Run your application

Next steps