> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bundleup.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js Quickstart

> Connect your first integration with a Next.js app using the BundleUp JavaScript SDK.

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](https://www.bundleup.io)
* 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

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

## 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:

<CodeGroup>
  ```shellscript npm theme={null}
  npm create next-app@latest bundleup-nextjs -- --yes
  cd bundleup-nextjs
  npm install
  ```

  ```shellscript pnpm theme={null}
  pnpm create next-app bundleup-nextjs --yes
  cd bundleup-nextjs
  pnpm install
  ```

  ```shellscript yarn theme={null}
  yarn create next-app bundleup-nextjs --yes
  cd bundleup-nextjs
  yarn install
  ```

  ```shellscript bun theme={null}
  bunx create-next-app bundleup-nextjs --yes
  cd bundleup-nextjs
  bun install
  ```
</CodeGroup>

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`.

<CodeGroup>
  ```shellscript npm theme={null}
  npm install @bundleup/sdk
  ```

  ```shellscript pnpm theme={null}
  pnpm add @bundleup/sdk
  ```

  ```shellscript yarn theme={null}
  yarn add @bundleup/sdk
  ```

  ```shellscript bun theme={null}
  bun add @bundleup/sdk
  ```
</CodeGroup>

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:

```bash .env.local lines theme={null}
# 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
NEXT_PUBLIC_BUNDLEUP_REDIRECT_URI=http://localhost:3000
```

<Warning>
  Your **API key** must remain server-side only. Never expose it in client-side code or environment variables prefixed with `NEXT_PUBLIC_`.
</Warning>

## 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`)

```typescript app/page.tsx lines theme={null}
export default function Home() {
  const url = `https://auth.bundleup.io/authorize?
client_id=${process.env.NEXT_PUBLIC_BUNDLEUP_CLIENT_ID}
&integration_id=${process.env.NEXT_PUBLIC_BUNDLEUP_INTEGRATION_ID}
&redirect_uri=${encodeURIComponent(`http://localhost:3000/callback`)}`;

  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 `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:

```typescript app/callback/page.tsx lines theme={null}
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:

```bash theme={null}
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