> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kobble.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Next quickstart
> Add authentication and permissions to your Next.js application using Kobble
## You will learn how to:
* Create a new React application using Next
* Configure `@kobbleio/next` SDK
* Protect your application routes
* Add permissions and quotas to your application
Pre-requisites: You need to [set up your Kobble account](/learning/quickstart/setup) before starting this guide.
## Example repository
To make your life simpler, we crafted various Next.js examples that you ca find in our [Next Examples Repository](https://github.com/kobble-io/kobble-next-examples).
## Installation
Scaffold your new Next application using [Next Create App](https://nextjs.org/docs/getting-started/installation).
```bash theme={null}
npx create-next-app@latest
```
Then, when prompted, choose the options you prefer for your project.
We recommend the following setup:
```bash theme={null}
What is your project named? my-app
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? Yes (mandatory)
Would you like to customize the default import alias (@/*)? Yes
What import alias would you like configured? @/*
```
It's mandatory to use App Router to work with the @kobbleio/next SDK.
```bash npm theme={null}
npm install @kobbleio/next
```
```bash yarn theme={null}
yarn add @kobbleio/next
```
```bash pnpm theme={null}
pnpm add @kobbleio/next
```
Our auth middleware allows you to protect your routes and handle the authentication flow seamlessly.
Create a `middleware.ts` file in your project and add the following code:
```ts theme={null}
import { authMiddleware } from '@kobbleio/next/server'
export default authMiddleware({
publicRoutes: ['/'],
});
export const config = {
matcher: [
// exclude internal Next.js routes
"/((?!.+\\.[\\w]+$|_next).*)",
// reinclude api routes
"/(api|trpc)(.*)"
]
};
```
This middleware will automatically expose various routes to handle authentication.
To leverage kobble utilities inside client side components, you need to wrap your app with the `KobbleProvider` component.
This is commonly done in the top level `layout.tsx` file.
Here's how your `layout.tsx` file should look like:
```tsx theme={null}
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import { KobbleProvider } from '@kobbleio/next/server';
import "./globals.css";
const inter = Inter({ subsets: ["latin"] });
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
{children}
);
}
```
Note that `KobbleProvider` itself is a server side component, and as such should not be rendered by a client component directly.
At this stage, if you run the project, you will get the following errors:
```bash theme={null}
тип Error: Missing NEXT_PUBLIC_KOBBLE_CLIENT_ID
```
This is because we need to add our Kobble Client ID and Customer Portal Domain to the environment variables.
If you don't know how to get these variables, it's covered in our [setup guide](/learning/quickstart/setup).
Create a `.env` file at the root of your project and add the following environment variables.
```env theme={null}
KOBBLE_CLIENT_SECRET=your-client-secret
NEXT_PUBLIC_KOBBLE_CLIENT_ID=your-client-id
NEXT_PUBLIC_KOBBLE_DOMAIN=your-domain-url
NEXT_PUBLIC_KOBBLE_REDIRECT_URI=http://localhost:3000/callback
```
**KOBBLE\_DOMAIN** and **KOBBLE\_CLIENT\_ID** can be found in [the Kobble Application we created earlier](/learning/quickstart/setup). The **REDIRECT\_URI** could be any route of your choice since the domain points to your Next Application.
## User authentication
In your client side code you can directly use the `useAuth` hook and various built-in components to manage your user's state and permissions.
Here's a simple example using ``, ``, ``, `` components:
```tsx theme={null}
'use client'
import {
useAuth,
SignedIn,
SignedOut,
LoginButton,
LogoutButton,
} from '@kobbleio/next/client'
export default function Home() {
const { user } = useAuth();
return (
Welcome, {user?.name}
Not authenticated
)
}
```
On your server code you can leverage @kobbleio/next/server utilities to handle user state and permissions.
```ts theme={null}
import { getAuth } from '@kobbleio/next/server'
export default async function handler(req, res) {
const { session } = await getAuth();
if (!session) {
return res.status(401).json({ error: 'Unauthorized' });
}
// An active session was found. User and tokens can be accessed from the session object.
console.log(session.user);
}
```
## Permissions and quotas
At this stage, you can manage your user's permissions and quotas client using our `` and `` components.
To learn more about [permissions](https://docs.kobble.io/product/permissions) and [quotas](https://docs.kobble.io/product/quotas), check out the [Kobble documentation](https://docs.kobble.io/product/permissions).
```tsx theme={null}
import {
IsAllowed,
IsForbidden,
SignedIn,
} from '@kobbleio/next/client'
export default function Home() {
return (
You're not allowed to generate images.
)
}
```
```ts theme={null}
import { getKobble } from '@kobbleio/next/server'
export default async function handler(req, res) {
const kobble = await getKobble();
const isAllowed = await kobble.acl.hasPermission('permission-name');
}
```
At this stage, you can manage your user's permissions and quotas client using our `` and `` components.
To learn more about [permissions](https://docs.kobble.io/product/permissions) and [quotas](https://docs.kobble.io/product/quotas), check out the [Kobble documentation](https://docs.kobble.io/product/permissions).
```tsx theme={null}
import {
IsAllowed,
IsForbidden,
SignedIn,
} from '@kobbleio/next/client'
export default function Home() {
return (
You're not allowed to generate images.
)
}
```
```ts theme={null}
import { getKobble } from '@kobbleio/next/server'
export default async function handler(req, res) {
const kobble = await getKobble();
const isAllowed = await kobble.acl.hasRemainingQuota('quota-name');
}
```
## Going further
This guide contained the basics to get you started with Kobble in your Next.js application.
However, there are many more features you can leverage to enhance your application.
Find more information in the [Kobble Next.js reference](/libraries/fullstack-sdk/next).