Установка и базовая настройка next-auth

1. Установка next-auth: шаг за шагом

В современном вебе “Вход через Google” стал почти обязательной кнопкой на каждом сайте. Даже если вы делаете простое приложение, рано или поздно встаёт вопрос: “А как отличить одного пользователя от другого? Как хранить их данные и защищать приватные страницы?” Вот тут и приходит на помощь библиотека next-auth — стандарт де-факто для аутентификации в Next.js.

next-auth — это мощная и гибкая библиотека для аутентификации, которая:

• Позволяет легко добавить вход через Google, GitHub, Email и десятки других провайдеров.
• Работает “из коробки” с App Router (и Page Router, если вдруг кто-то скучает по старому).
• Позволяет реализовать как простую, так и кастомную логику входа, управления сессией и защиты маршрутов.

Интересный факт: next-auth настолько популярен, что иногда его называют “React Passport”, намекая на легендарный passport.js для Node Express.

Подготовка проекта

Для начала убедитесь, что у вас есть проект на Next.js 15+, использующий App Router (структура с папкой app/). Если вы только учитесь, можно создать новый проект:

npx create-next-app@latest my-auth-app
cd my-auth-app

Совет: Если у вас уже есть проект, просто переходите к следующему шагу.

Установка пакета

Установим саму библиотеку и типы (если вы на TypeScript):

npm install next-auth
# или
yarn add next-auth

Если вы используете TypeScript (а вы, скорее всего, уже к нему привыкли), добавьте типы:

npm install -D @types/next-auth

Лайфхак: В новых версиях next-auth типы идут вместе с пакетом, так что отдельная установка типов часто не нужна.

2. Базовая настройка next-auth в Next.js 15 (App Router)

Где настраивать? Новый подход

В App Router, аутентификация настраивается через Route Handlers в папке app/api/auth/[...nextauth]/route.ts (или .js). Именно сюда Next.js будет отправлять все запросы, связанные с аутентификацией.

Почему такая странная папка?
[...] — это “catch-all” сегмент маршрута, позволяющий next-auth обрабатывать все свои внутренние эндпоинты (/api/auth/signin, /api/auth/callback, и т.д.).

Создаём файл маршрута next-auth

Создайте папку и файл:

app/
  api/
    auth/
      [...nextauth]/
        route.ts

Если у вас JavaScript-проект, используйте route.js.

Минимальная конфигурация (пример с GitHub)

Давайте настроим самый простой способ входа — через GitHub. Для этого понадобятся Client ID и Client Secret, которые можно получить в настройках OAuth Apps на GitHub Developer Settings.

import NextAuth from "next-auth";
import GitHubProvider from "next-auth/providers/github";

// В реальном проекте храните секреты в .env.local!
export const authOptions = {
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID || "",
      clientSecret: process.env.GITHUB_SECRET || "",
    }),
  ],
};

const handler = NextAuth(authOptions);

export { handler as GET, handler as POST };

Пояснения:
NextAuth — функция, создающая обработчик для Route Handler.
providers — массив провайдеров входа. Здесь можно добавить Google, Email, Discord и других.
clientId и clientSecret — данные, которые вы получите в настройках GitHub OAuth App.
В конце экспортируются два метода: GET и POST — это нужно для корректной работы next-auth эндпоинтов.

Важно: Никогда не храните секреты прямо в коде! Используйте переменные окружения (.env.local):

GITHUB_ID=ваш_идентификатор
GITHUB_SECRET=ваш_секрет
NEXTAUTH_URL=http://localhost:3000

3. Добавляем провайдеры: Google, Email и другие

Добавить вход через Google так же просто:

import GoogleProvider from "next-auth/providers/google";

providers: [
  GitHubProvider({
    clientId: process.env.GITHUB_ID || "",
    clientSecret: process.env.GITHUB_SECRET || "",
  }),
  GoogleProvider({
    clientId: process.env.GOOGLE_CLIENT_ID || "",
    clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
  }),
]

Интересный факт: next-auth поддерживает десятки провайдеров “из коробки” — от VK до Apple и даже Steam. Полный список — в документации.

4. Использование next-auth на клиенте: кнопки входа и выхода

Добавляем кнопки входа и выхода

Для управления сессией на клиенте (например, чтобы показать “Войти” или “Выйти”), используйте специальные хуки и функции из next-auth/react.

"use client";

import { signIn, signOut, useSession } from "next-auth/react";

export default function AuthButtons() {
  const { data: session, status } = useSession();

  if (status === "loading") return <p>Загрузка...</p>;
  if (session)
    return (
      <div>
        <p>Привет, {session.user?.name || session.user?.email}!</p>
        <button onClick={() => signOut()>Выйти</button>
      </div>
    );
  return <button onClick={() => signIn()>Войти</button>;
}

Лайфхак: signIn() без параметров покажет стандартную страницу выбора провайдера. Можно передать, например, "github", чтобы сразу открыть окно GitHub.

Где размещать компонент?

Обычно компонент с кнопками входа/выхода размещают в шапке сайта (layout.tsx или отдельном компоненте Header), чтобы он был доступен на всех страницах.

5. Полезные нюансы

Проверка работы: первый вход

1. Запустите приложение:
   

   npm run dev

2. Перейдите по адресу http://localhost:3000/api/auth/signin
3. Должна открыться стандартная страница входа next-auth с выбором провайдера.
4. После успешного входа next-auth создаст сессию (куки) и будет знать, кто вы.

Где хранится сессия? (и почему это удобно)

• По умолчанию next-auth хранит сессию в cookie (JWT).
• Можно подключить базу данных для хранения пользователей, токенов и т.п. (это уже “продвинутый уровень”).
• Сессия автоматически доступна на сервере и клиенте — можно защищать страницы, показывать личные данные и т.д.

Быстрая интеграция с приложением

Допустим, у нас есть страница профиля /profile, которая должна быть доступна только авторизованным пользователям.

import { auth } from "next-auth";
import { redirect } from "next/navigation";

export default async function ProfilePage() {
  const session = await auth();

  if (!session) {
    redirect("/api/auth/signin");
  }

  return (
    <div>
      <h1>Профиль</h1>
      <p>Добро пожаловать, {session.user?.name || session.user?.email}!</p>
    </div>
  );
}

Фишка: В App Router можно вызывать auth() прямо в Server Component — это суперудобно!

6. Типичные ошибки при установке и настройке next-auth

Ошибка №1: Не создали файл route.ts по адресу app/api/auth/[...nextauth]/route.ts.
Если файл называется иначе (например, nextauth.ts или лежит не в той папке), next-auth просто не будет работать. Всегда проверяйте структуру папок!

Ошибка №2: Не указаны переменные окружения или указаны неверно.
Если забыть про GITHUB_ID, GITHUB_SECRET или опечататься в них, next-auth не сможет подключиться к провайдеру, и вы увидите ошибку “No client id” или “No client secret”.

Ошибка №3: Использование Client Component без "use client".
Если вы используете useSession или signIn в компоненте, но забыли добавить строку "use client"; в начало файла, получите ошибку во время сборки или при рендере.

Ошибка №4: Не экспортированы оба метода — GET и POST.
Если экспортировать только один (GET или POST), часть эндпоинтов next-auth работать не будет, и вы получите странные ошибки при попытке входа или выхода.

Ошибка №5: Несовпадение версий Next.js и next-auth.
next-auth быстро развивается, и иногда свежие фичи требуют актуальной версии Next.js. Если что-то не работает, проверьте, не устарел ли ваш next-auth.

Ошибка №6: Не указана переменная NEXTAUTH_URL в .env.local.
Без неё next-auth не сможет корректно формировать URL для редиректов, особенно если вы деплоите приложение.