Skip to main content

Migrating to v42

This guide will help you migrate @krakentech/blueprint-auth to version 42, which simplifies cookie access and introduces forwardHeaders for proper request header and cookie forwarding.

Overview​

Version 42 simplifies how you read authentication cookies. The getCookieMapItem helper and getRefreshToken have been removed in favor of standard Map methods, and getAuthCookies() now returns only cookies that are actually set.

A new forwardHeaders utility is also available for apps that need middleware-set headers and cookies to be visible downstream.

Help us improve this guide

If you identify a breaking change we've missed, please reach out so we can add it to this page. If you run into any issues during migration, don't hesitate to reach out to the team for support.

Migration Steps​

Step 1: Update packages​

pnpm update @krakentech/blueprint-auth@^42

Step 2: Replace getCookieMapItem with standard Map methods​

getCookieMapItem has been removed from both createAuthCookieUtils and createAppRouterAuth. getAuthCookies() now returns a Map<CookieName, string> containing only cookies that are set, so you can use standard Map methods directly.

// Before
const { getAuthCookies, getCookieMapItem } = createAuthCookieUtils(authConfig, {
  context,
});
const cookies = await getAuthCookies();
const token = getCookieMapItem({ cookies, name: "accessToken" })?.value;
const hasToken = Boolean(getCookieMapItem({ cookies, name: "accessToken" }));

// After
const { getAuthCookies } = createAuthCookieUtils({}, { context });
const cookies = await getAuthCookies();
const token = cookies.get("accessToken");
const hasToken = cookies.has("accessToken");

getRefreshToken has been removed from both createAuthCookieUtils and createAppRouterAuth. Read the refresh token directly from the cookie map returned by getAuthCookies():

// Before
const { getRefreshToken } = createAuthCookieUtils({}, { context });
const refreshToken = await getRefreshToken();
const tokenValue = refreshToken?.value;

// After
const { getAuthCookies } = createAuthCookieUtils({}, { context });
const cookies = await getAuthCookies();
const refreshToken = cookies.get("MWRefreshToken") ?? cookies.get("refreshToken");

Step 4: Use forwardHeaders for post-auth mutations​

tip

You can skip this step if your middleware only calls createAuthMiddleware and does not modify headers or cookies afterward.

If you run additional middleware logic after authMiddleware that sets headers or cookies, wrap the final response with forwardHeaders to ensure they are visible in Server Components via headers() from next/headers, or in getServerSideProps via context.req.headers:

middleware.ts
import {
  createAuthMiddleware,
  forwardHeaders,
} from "@krakentech/blueprint-auth/middleware";
import { setFeatureFlagCookies } from "@/lib/feature-flags";
import { authConfig } from "@/lib/auth/config";
import type { NextRequest } from "next/server";

const authMiddleware = createAuthMiddleware(authConfig);

export async function middleware(request: NextRequest) {
  const response = await authMiddleware(request);

  // Headers/cookies modified after authMiddleware require forwardHeaders
  const finalResponse = setFeatureFlagCookies({ res: response });

  return forwardHeaders(request, finalResponse);
}