Next.js Quickstart

Get started with BundleUp in your Next.js application in under 5 minutes. This guide walks you through connecting to a third-party API using GitHub as an example, but the same flow applies to any supported integration. By the end of this guide, you’ll:

Redirect a user through an OAuth-style authorization flow
Receive a connection_id
Use that connection_id to make unified API calls via BundleUp

Prerequisites

Before you begin, make sure you have:

A BundleUp account
A BundleUp API key (server-side)
Your BundleUp Client ID (used for authorization redirects)
An Integration ID for the service you want to connect (for example, github)
Node.js 18+ installed

You can find your API key, Client ID, and Integration IDs in the BundleUp dashboard.

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 BundleUp’s 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

export default function Home() {
  const url = new URL("https://auth.bundleup.io/authorize");
  url.searchParams.set("client_id", process.env.BUNDLEUP_CLIENT_ID!);
  url.searchParams.set("integration_id", process.env.BUNDLEUP_INTEGRATION_ID!);
  url.searchParams.set("redirect_uri", process.env.BUNDLEUP_REDIRECT_URI!);

  return (
    <div className="flex items-center justify-center p-4">
      <a
        href={url.toString()}
        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 connection_id. This 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) 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<{
    error?: string;
    error_description?: string;
    connection_id: string;
  }>;
}

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

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

  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>
  );
}

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.

What’s next?

Store the connection_id in your database
Use it across API routes, server actions, or background jobs
Add support for additional integrations with zero auth changes

Get started

SDK

Proxy

MCP

Unified API

Platform API

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

What’s next?

​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

​What’s next?

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

What’s next?