Next Bungie Auth

Next Bungie Auth is an open source Next.js library that provides a configurable solution for
authenticating your users with Bungie.net

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

$3

- Next.js 15.0 or later
- Registered Bungie developer application
1. Select Confidential OAuth Client Type
2. Set your redirect url to https://localhost:3000/your-custom-path
- Note: you should create a separate application for production

$3

1. Install the package

npm install next-bungie-auth or yarn add next-bungie-auth or bun add next-bungie-auth

2. Update .env file with your Bungie.net Application credentials:

``env
BUNGIE_CLIENT_ID=OAuth_client_id
BUNGIE_CLIENT_SECRET=OAuth_client_secret
`

Usage

On the server side, you can use the createNextBungieAuth function from next-bungie-auth/server to create Bungie auth handlers and server-side helpers.

See " class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">NextBungieAuthConfig for a list of all options.

`ts
// /app/api/auth/index.ts
import "server-only"; // this is an optional npm package which prevents your from accidentally importing server code on the client
import { createNextBungieAuth } from "next-bungie-auth/server";

export const {
catchAllHandler,
serverSideHelpers: { getServerSession },
} = createNextBungieAuth({
// Pass your config here
clientId: process.env.BUNGIE_CLIENT_ID!,
clientSecret: process.env.BUNGIE_CLIENT_SECRET!,
// You can generate state however you want
generateState: () => crypto.randomUUID(),
});
`

$3

The createNextBungieAuth function provides several route handlers that you can use in your Next.js API routes.

- authorizeGET: Redirects the user to Bungie's OAuth page
- deauthorizePOST: Deauthorizes the user's session
- callbackGET: Handles the OAuth callback from Bungie
- sessionGET: Returns the current session
- refreshPOST: Refreshes the current session

However, the easier way is to use the catch-all route handler, which will automatically set up the routes for you.

`ts
// /app/api/auth/[...bungie]/route.ts
import { catchAllHandler } from "..";

const { GET, POST } = catchAllHandler;

export { GET, POST };
`

To use the Bungie authentication in your Next.js pages, you can use the useBungieSession hook from client.tsx. This hook provides the current Bungie session context.

$3

Now that you have set up your server-side logic, it is likely that you will also be making client-side requests on behalf of the user.

You can use the BungieSessionProvider from client.tsx to provide a Bungie session context to your components. It is recommended to place this component in the root layout. This provider takes several options:

- initialSession: The initial session data.
- enableAutomaticRefresh: (Default true) Whether to enable automatic session refresh.
- refreshInBackground: Whether or not automatic refreshes happen when the browser tab is hidden
- ...and more. See BungieSessionProviderParams in types.ts

`tsx
// /app/layout.tsx
import { getServerSession } from "./api/auth";
import { BungieSessionProvider } from "next-bungie-auth/client";
import { cookies } from "next/headers";

export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
// Optional: to avoid extra round trips, grab the session from the cookies at the time of the request
const cookieJar = await cookies();
const session = getServerSession(cookieJar);

return (




`tsx
// /app/my-component.tsx
"use client";

import { useBungieSession } from "next-bungie-auth/client";

export const MyComponent = () => {
const session = useBungieSession();

if (session.isPending) return

{JSON.stringify(session, null, 2)}

In order to use Bungie's OAuth, you must use HTTPS. Next.js provides built in support with version 13.5 and above, using the --experimental-https flag. Update your dev command to use next dev --experimental-https if you do not have any custom proxy solution.

What does this library not do?

This library does not handle most network errors or refetching client side on an error. The session state provides the tools needed to identify a network or client error and refetch, but the user will need to manually implement this retry logic

Questions?

Reach out to _newo` on Discord!

License

This project is licensed under the MIT License - see the LICENSE.md file for details