added explicit intent, inputs with env var and external connection setup, 10-step procedure covering session creation through CSRF validation, 9 decision points for meta placement/inheritance/auth/cookies/secrets/edge cases, and clear output contract plus outcome signals for each feature.

Remix v2 Meta, Sessions, Auth, and CSRF

intent

Build SEO-safe document heads, secure cookie sessions, auth gates, and CSRF protection in Remix v2. use this skill when you need to set meta tags (title, OG, canonical), manage user sessions with secure cookies, gate routes to authenticated users only, or defend mutations against cross-site request forgery. v2 changed the meta shape from objects to arrays and removed automatic parent merging; this skill covers all four concerns together because they're tightly coupled in auth flows.

inputs

environment variables:

SESSION_SECRET (required): at least 32 random characters, used to sign session cookies. rotate by adding old secret to SESSION_SECRET_OLD.
NODE_ENV: set to "production" to enforce secure cookies (https-only, strict sameSite).

external connections:

remix-utils/csrf: npm package for signed CSRF tokens (separate cookie, not reused from session). set up via createCookie("csrf", { secrets: [...] }).
remix-auth: optional npm package for OAuth/social login, manages login/logout flow. requires strategy setup (google, github, etc.).
session storage: defaults to HTTP-only cookies; can swap to database-backed sessions via custom createSessionStorage (slower, but survives server restarts).

route-level context:

request.headers.get("Cookie"): always passed to getSession() to hydrate session data.
request object in loaders/actions: needed to extract userId, check CSRF, and throw auth redirects.
route matches array in MetaFunction: passed automatically, used to flatMap parent meta and find parent loader data.

procedure

step 1: set up session storage (once, in app/session.server.ts)

input: SESSION_SECRET, SESSION_SECRET_OLD env vars, session data types.

import createCookieSessionStorage from @remix-run/node.
define two types: SessionData (userId, username, etc.) and SessionFlashData (error, success messages).
require SESSION_SECRET at runtime; throw if missing (do not silently default).
build secrets array: [SESSION_SECRET, ...(SESSION_SECRET_OLD ? [SESSION_SECRET_OLD] : [])].
call createCookieSessionStorage({ cookie: { name: "__session", httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "lax", path: "/", maxAge: 60*60*24*30, secrets: [...] } }).
export { getSession, commitSession, destroySession } from the module.

output: three session functions ready to import. old sessions (signed with SESSION_SECRET_OLD) still validate; new sessions sign with SESSION_SECRET.

step 2: wrap root.tsx with Meta and Links aggregators

input: existing app/root.tsx, route tree.

import { Links, Meta, Scripts, ScrollRestoration, LiveReload, Outlet } from @remix-run/react.
place <Meta /> and <Links /> inside <head> (after charset/viewport meta tags).
place <ScrollRestoration />, <Scripts />, <LiveReload /> at the end of <body> (before closing tag).
nest <Outlet /> in <body> to render matched routes.

output: root component structure that aggregates all child route meta and links. without this, CSS loads async and meta tags vanish.

step 3: export meta from routes (per-route, in leaf routes)

input: loader data type, parent route IDs (if merging parent meta), MetaFunction type.

import type { MetaFunction } from @remix-run/node.
define export const meta: MetaFunction<typeof loader, { "routes/parent.$id": typeof parentLoader }> with both generics.
return an array of descriptor objects: [{ title: "..." }, { name: "description", content: "..." }, { property: "og:title", content: "..." }, { tagName: "link", rel: "canonical", href: "..." }].
if inheriting parent meta, call matches.flatMap((m) => m.meta ?? []) first, then append route-specific tags.
handle missing data: if data?.post is falsy, return [{ title: "Not Found" }] early.

output: array of tag descriptors. Remix renders them in <head> in the order returned.

step 4: create requireUserId auth helper (once, in app/auth.server.ts)

input: getSession, session data type, redirect from @remix-run/node.

import { redirect } from @remix-run/node and { getSession } from ./session.server.
define export async function requireUserId(request: Request): Promise<string>.
inside: extract cookies via request.headers.get("Cookie").
call getSession(cookies) and read userId via session.get("userId").
if userId is falsy, construct redirect URL: new URL(request.url) then ${pathname}${search}.
throw redirect(/login?redirectTo=${encodeURIComponent(redirectTo)}) (do not return; throw it).
if userId exists, return it as string.

output: synchronous helper that throws 302 redirects on auth failure, short-circuiting the loader.

step 5: gate loaders with requireUserId

input: loader function, requireUserId helper, request parameter.

call await requireUserId(request) at the top of the loader (before any data fetches).
if the request is unauthenticated, the throw bubbles up; Remix catches it and sends the redirect response.
if authenticated, continue with loader logic.

output: GET requests from unauthenticated users redirect to login. authenticated users enter the loader.

step 6: commit sessions in loaders (on mutations and auth changes)

input: session object, commitSession function, response headers object.

after calling session.set("userId", newUserId) or session.flash("error", "..."), do not just return json/redirect.
invoke await commitSession(session) to serialize the session into a signed cookie string.
attach as header: return redirect("/dashboard", { headers: { "Set-Cookie": await commitSession(session) } }) or return json(data, { headers: { "Set-Cookie": await commitSession(session) } }).
if no header is attached, the session write is silently dropped.

output: Set-Cookie response header with signed session cookie. browser stores it for future requests.

step 7: destroy sessions (logout action)

input: destroySession function, session object, POST action.

in the logout action (not loader), call await destroySession(session) (no session.set needed).
return redirect("/", { headers: { "Set-Cookie": await destroySession(session) } }).
the Set-Cookie header includes max-age=0, clearing the cookie client-side immediately.

output: user is logged out. next request has no session cookie.

step 8: set up CSRF protection with remix-utils/csrf

input: remix-utils/csrf npm package, separate CSRF cookie, signed secrets.

npm install remix-utils (or yarn add).
create app/csrf.server.ts, import createCookie from @remix-run/node and csrf functions from remix-utils/csrf.
define a dedicated cookie: const csrfCookie = createCookie("csrf", { httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "lax", secrets: [CSRF_SECRET, ...] }).
call const { commitToken, validateToken } = await initializeCsrf(csrfCookie, request) in loaders and actions.
export both for use in components and actions.

output: CSRF cookie and token helpers. do not reuse the session cookie; they have different serialization formats and will throw on validate.

step 9: embed CSRF tokens in forms

input: AuthenticityTokenInput from remix-utils/csrf, loader that calls initializeCsrf.

in loaders, call const { commitToken } = await initializeCsrf(csrfCookie, request).
return token to component: return json({ csrfToken: commitToken() }, { headers: { "Set-Cookie": await csrfCookie.serialize(...) } }).
in component, import AuthenticityTokenInput from remix-utils/csrf.
place <AuthenticityTokenInput token={csrfToken} /> inside every <Form method="post">.

output: hidden input field with signed CSRF token. form POST includes it automatically.

step 10: validate CSRF in actions

input: validateToken from csrf setup, action request, form data.

at the top of every POST/PUT/DELETE action, call await validateToken(request).
if validation fails (token missing, expired, or invalid), validateToken throws a 403.
if validation passes, continue with action logic.

output: cross-site POST requests are rejected. same-origin forms proceed.

decision points

when to use meta vs plain JSX in head?

if the tag is site-wide (charset, viewport, default OG image for social shares): place it as plain JSX inside <head> in root.tsx. this avoids the v2 no-merge behavior and prevents duplicates.
else the tag is route-specific (page title, description, canonical URL, JSON-LD): export meta from the leaf route. if you need parent values, flatMap matches manually.

when does meta inherit from parents?

in v1, meta was auto-merged (last-write-wins per key).
in v2, meta does NOT auto-merge. Remix picks the last matching route's meta array only. to inherit parent meta, you must explicitly call matches.flatMap((m) => m.meta ?? []) and spread the result into your array.

when to protect: loader vs action?

if it's a GET that must be protected (only authenticated users can see the page): call await requireUserId(request) at the top of the loader.
if it's a POST/PUT/DELETE that must be protected (mutation, state change): call await requireUserId(request) AND await validateToken(request) at the top of the action.
if it's a logout: use an action (POST), never a loader (GET). a link to a logout loader is CSRF-able via <img src="/logout">. use <Form method="post" action="/logout"> instead.

session cookie: when to commit?

every time you call session.set() or session.flash(): you must return a Set-Cookie header. silent drops are the top auth bug.
on login: set userId, commit, redirect.
on logout: destroy session, commit, redirect.
on flash (error message, success toast): flash the data, commit, return (or redirect).
on plain reads with no changes: no commit needed.

CSRF: signed cookie vs SameSite alone?

if you use remix-utils/csrf: create a dedicated CSRF cookie (separate from session). sign it with CSRF_SECRET. validate every POST/PUT/DELETE with validateToken(request). this defends against csrf even if an attacker tricks a user into visiting a malicious site (because the attacker never sees the CSRF cookie value, only the server does).
if you don't use a library: set sameSite: "lax" on the session cookie and verify the Origin header in actions. Lax blocks cookies on cross-site POST but allows top-level GET navigations (intended behavior for deep links from external sites). prefer adding remix-utils/csrf instead of rolling your own.
never use `sameSite: "none" unless you have a legitimate cross-origin need (OAuth popups, iframe embeds). None disables all cookie-level CSRF protection and requires HTTPS.

session secret rotation?

to rotate: generate a new secret string, keep the old one, set SESSION_SECRET to new and SESSION_SECRET_OLD to old.
old sessions still validate because the secrets array includes both.
new sessions sign with the first secret (SESSION_SECRET).
after grace period (when all old sessions are expired), remove SESSION_SECRET_OLD and redeploy.

missing or falsy data in meta?

if data?.post is missing (404, deleted, permission denied), return early: if (!data?.post) return [{ title: "Not Found" }].
do not render meta tags with null or undefined values; leave them out of the array entirely.

edge case: session and CSRF cookies expire at different times?

session cookie: maxAge (in seconds) controls expiry. set to 30 days (606024*30) by default.
CSRF cookie: expires faster than session (usually). if a user's session expires but CSRF is still valid, the next mutation fails CSRF validation. return a 403 and prompt them to refresh.
to avoid surprise logouts: ensure CSRF maxAge matches or exceeds session maxAge.

edge case: empty result sets in meta?

if an array returns empty [], Remix renders no meta tags for that route. parent routes' meta is not inherited.
always include at least a title: [{ title: data?.name || "Untitled" }].

edge case: network timeout fetching data for meta?

meta functions must not be slow (under 100ms ideal). if your data fetch times out, the entire page render stalls.
move slow fetches to loaders, not meta. meta should read synchronously from loader data only.
never call external APIs from meta; they will hang the page.

edge case: CSRF token missing from form?

if AuthenticityTokenInput is missing from a form and you call validateToken(request), the request throws 403.
check: is AuthenticityTokenInput inside the form? is the hidden input name correct (default "csrf")?
for manual fetch(), add the token manually: fetch("/api/x", { method: "POST", headers: { "csrf-token": token }, body: JSON.stringify(...) }) and validate with custom header check.

edge case: reusing session cookie for CSRF?

session cookie serializes a JS object (userId, email, roles, etc.).
CSRF cookie is a signed string (opaque token).
if you try to use one cookie for both, validateToken() will fail to parse the session object as a CSRF token. throw separately, do not reuse.

output contract

meta export: returns array of tag descriptor objects. each object has at least one of: title, name + content, property + content, tagName + attributes. Remix renders them as HTML tags in <head> in the order returned. no duplicate tags (deduping is your responsibility).

session functions: getSession(cookieHeader) returns a session object with .get(key) and .set(key, value) methods. commitSession(session) returns a string (cookie header value). destroySession(session) returns a string (cookie header value, max-age=0).

requireUserId function: takes request: Request, returns Promise<string> (userId). throws Response (302 redirect) on auth failure.

CSRF validate function: takes request: Request, returns Promise<string> (the CSRF token). throws Response (403 Forbidden) on invalid/missing token.

Set-Cookie header: placed in response headers, sent to browser. browser parses ; path=/; max-age=...; secure; httpOnly; sameSite=... and stores cookie for future requests. multiple Set-Cookie headers can be sent in one response (for session and CSRF cookies).

outcome signal

meta tags render: view page source (Ctrl+U), search for <title>, <meta name="description">, <meta property="og:title">. if absent, check that meta export returns an array (not an object) and that route is matched.
session persists: log in, refresh the page, still logged in. log out, refresh the page, redirects to login. if you're logged in but session.set() was called and lost, you forgot the Set-Cookie header in the response.
auth redirects work: try accessing a protected route without logging in. you should see a 302 redirect to /login?redirectTo=... in the network tab. the page never renders; the loader throws before returning HTML.
CSRF validates: submit a form with AuthenticityTokenInput. network tab shows 200. submit the same form from a malicious cross-origin site (in console, change the form action to point to your app). network tab shows 403 Forbidden. if forms fail on your own site, check that you're calling validateToken(request) in the action.
session expiry: after maxAge time passes (or manually delete cookie in DevTools), next request shows no session data. refresh the page, redirects to login if protected.
secret rotation: deploy new SESSION_SECRET, keep SESSION_SECRET_OLD. old user sessions still work. new logins use the new secret. after grace period, remove old secret and redeploy.

Remix V2 Meta Sessions

related skills