Next.js

This is the documentation for Edge-CSRF's Next.js integration. The integration works with Next.js 13, 14 and 15.

Quickstart

First, add the integration library as a dependency to your app:

1npm install @edge-csrf/nextjs
2# or
3pnpm add @edge-csrf/nextjs
4# or
5yarn add @edge-csrf/nextjs

Next, create a middleware file (middleware.ts) for your project and add the Edge-CSRF middleware:

1// middleware.ts
2
3import { createCsrfMiddleware } from '@edge-csrf/nextjs';
4
5// initalize csrf protection middleware
6const csrfMiddleware = createCsrfMiddleware({
7  cookie: {
8    secure: process.env.NODE_ENV === 'production',
9  },
10});
11
12export const middleware = csrfMiddleware;

Now, all HTTP submission requests (e.g. POST, PUT, DELETE, PATCH) will be rejected if they do not include a valid CSRF token. To add the CSRF token to your forms, you can fetch it from the X-CSRF-Token HTTP response header server-side or client-side. For example:

App Router

1// app/page.tsx
2
3import { headers } from 'next/headers';
4
5export default async function Page() {
6  const h = await headers();
7  const csrfToken = h.get('X-CSRF-Token') || 'missing';
8
9  return (
10    <form action="/api/form-handler" method="post">
11      <input type="hidden" value={csrfToken}>
12      <input type="text" name="my-input">
13      <input type="submit">
14    </form>
15  );
16}

1// app/form-handler/route.ts
2
3import { NextResponse } from 'next/server';
4
5export async function POST() {
6  return NextResponse.json({ status: 'success' });
7}

Pages Router

1// pages/form.ts
2
3import type { NextPage, GetServerSideProps } from 'next';
4import React from 'react';
5
6type Props = {
7  csrfToken: string;
8};
9
10export const getServerSideProps: GetServerSideProps = async ({ res }) => {
11  const csrfToken = res.getHeader('x-csrf-token') || 'missing';
12  return { props: { csrfToken } };
13}
14
15const FormPage: NextPage<Props> = ({ csrfToken }) => {
16  return (
17    <form action="/api/form-handler" method="post">
18      <input type="hidden" value={csrfToken}>
19      <input type="text" name="my-input">
20      <input type="submit">
21    </form>
22  );
23}
24
25export default FormPage;

1// pages/api/form-handler.ts
2
3import type { NextApiRequest, NextApiResponse } from 'next';
4
5type Data = {
6  status: string
7};
8
9export default function handler(req: NextApiRequest, res: NextApiResponse<Data>) {
10  // this code won't execute unless CSRF token passes validation
11  res.status(200).json({ status: 'success' });
12}

Examples

Here are some examples in this repository:

Version	Router	Implementation
Next.js 13	app router	HTML form
Next.js 13	app router	JavaScript (dynamic)
Next.js 13	app router	JavaScript (static)
Next.js 13	pages router	HTML form
Next.js 14	app router	HTML form
Next.js 14	app router	JavaScript (dynamic)
Next.js 14	app router	JavaScript (static)
Next.js 14	app router	Sentry
Next.js 14	app router	Server action (form)
Next.js 14	app router	Server action (non-form)
Next.js 14	pages router	HTML form
Next.js 15	app router	HTML form
Next.js 15	app router	JavaScript (dynamic)
Next.js 15	app router	JavaScript (static)
Next.js 15	app router	Sentry
Next.js 15	app router	Server action (form)
Next.js 15	app router	Server action (non-form)
Next.js 15	pages router	HTML form

Lower-level implementations

If you want lower-level control over the response or which routes CSRF protection will be applied to you can use the createCsrfProtect() method to create a function that you can use inside your own custom middleware:

1// middleware.ts
2
3import { CsrfError, createCsrfProtect } from '@edge-csrf/nextjs';
4import { NextResponse } from 'next/server';
5import type { NextRequest } from 'next/server';
6
7// initalize csrf protection method
8const csrfProtect = createCsrfProtect({
9  cookie: {
10    secure: process.env.NODE_ENV === 'production',
11  },
12});
13
14// Next.js middleware function
15export const middleware = async (request: NextRequest) => {
16  const response = NextResponse.next();
17
18  try {
19    await csrfProtect(request, response);
20  } catch (err) {
21    if (err instanceof CsrfError) return new NextResponse('invalid csrf token', { status: 403 });
22    throw err;
23  }
24
25  return response;
26};

Configuration

1// default config
2
3{
4  cookie: {
5    name: '_csrfSecret',
6    path: '/',
7    maxAge: undefined,
8    domain: '',
9    secure: true,
10    httpOnly: true,
11    sameSite: 'strict'
12  },
13  excludePathPrefixes: ['/_next/'],
14  ignoreMethods: ['GET', 'HEAD', 'OPTIONS'],
15  saltByteLength: 8,
16  secretByteLength: 18,
17  token: {
18    fieldName: 'csrf_token',
19    responseHeader: 'X-CSRF-Token',
20    value: undefined
21  }
22}

API

The following are named exports in the the @edge-csrf/nextjs module:

Types

NextCsrfProtect - A function that implements CSRF protection for Next.js requests

  * @param {NextRequest} request - The Next.js request instance
  * @param {NextResponse} response - The Next.js response instance
  * @returns {Promise<void>} - The function completed successfully
  * @throws {CsrfError} - The function encountered a CSRF error

Classes

CsrfError - A class that inherits from Error and represents CSRF errors

Methods

createCsrfMiddleware([, options]) - Create a new instance of Next.js middleware

  * @param {object} options - The configuration options
  * @returns {Middleware} - The middleware

createCsrfProtect([, options]) - Create a lower-level function that can be used inside Next.js middleware
                                 to implement CSRF protection for requests

  * @param {object} options - The configuration options
  * @returns {NextCsrfProtect} - The CSRF protection function