SameSite=None Cookie Compatibility Utility

Common errors

• Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client

  cause This error occurs when an Express middleware (or other code) attempts to modify HTTP headers or send a response after the HTTP response has already been sent to the client. In older versions of `should-send-same-site-none`, specifically before 2.0.5, the middleware could sometimes trigger this.
  fix Update `should-send-same-site-none` to version `2.0.5` or later. Also, ensure that your Express routes and other middleware functions send only one response per request and use `return` statements after sending a response to prevent further execution.

• Cookies with SameSite=None; Secure are not being set or sent by the browser

  cause This issue typically arises for two primary reasons: either the `Secure` attribute is missing when `SameSite=None` is used (which is a modern browser requirement) or the user agent is one of the known incompatible browsers that explicitly rejects `SameSite=None`.
  fix Ensure all `SameSite=None` cookies are explicitly set with `secure: true`. Additionally, implement `should-send-same-site-none` to detect and handle incompatible user agents, allowing the library to remove `SameSite=None` for those specific clients, thus ensuring the cookie is still sent (potentially as `SameSite=Lax` default) and preventing rejection.

Warnings

• gotcha Cookies marked with `SameSite=None` MUST also be marked `Secure=true`. This library only handles the `SameSite` attribute compatibility and does NOT automatically add the `Secure` attribute. Failure to add `Secure` will result in browsers rejecting the cookie, regardless of `SameSite` compatibility.
  Fix: Always set the `secure: true` option when setting cookies with `sameSite: 'none'`, e.g., `res.cookie('name', 'value', { sameSite: 'none', secure: true });`.
• breaking In previous versions (before v2.0.5), the Express middleware could sometimes cause an `ERR_HTTP_HEADERS_SENT` error due to attempting to modify headers after they had already been sent. This typically occurred in specific scenarios where the response cycle was interrupted or completed before the middleware finished its operations.
  Fix: Upgrade to version `2.0.5` or newer to resolve the `ERR_HTTP_HEADERS_SENT` issue. This version includes a fix that properly handles response headers to prevent this error.
• gotcha The core problem this library addresses is that some older browsers (Chrome 51-66, certain Safari, UC Browser) explicitly reject cookies with `SameSite=None`, treating them as invalid. Without this library, developers would need to manually maintain a list of incompatible user agents and adjust cookie settings, potentially leading to broken cross-site cookie functionality on these clients.
  Fix: Integrate `should-send-same-site-none` into your application, either using the `isSameSiteNoneCompatible` utility function for manual checks or the `shouldSendSameSiteNone` Express middleware for automatic handling, especially if supporting older browsers for cross-site cookie functionality.

Install

• npm install should-send-same-site-none npm
• yarn add should-send-same-site-none yarn
• pnpm add should-send-same-site-none pnpm

Imports

• isSameSiteNoneCompatible
  wrong:

  const isSameSiteNoneCompatible = require('should-send-same-site-none').isSameSiteNoneCompatible;

  correct:

  import { isSameSiteNoneCompatible } from 'should-send-same-site-none';

  For ESM projects, use named import. CommonJS projects should use destructuring from `require`.
• shouldSendSameSiteNone
  wrong:

  const shouldSendSameSiteNone = require('should-send-same-site-none'); // Incorrect: it's a named export
  const { shouldSendSameSiteNone: middleware } = require('should-send-same-site-none'); // Correct for CJS

  correct:

  import { shouldSendSameSiteNone } from 'should-send-same-site-none';

  The Express middleware is a named export. Ensure correct destructuring for CommonJS or direct named import for ESM. Incorrectly trying to `require` the default export will fail.
• *

  import * as SameSiteNone from 'should-send-same-site-none';

  While possible, direct named imports are generally preferred for tree-shaking and clarity in modern JavaScript and TypeScript environments.

Quickstart

Demonstrates setting up the Express middleware to automatically manage `SameSite=None` cookie attributes for incompatible user agents, ensuring cross-site cookie functionality while adhering to modern browser security policies.

import express from 'express';
import { shouldSendSameSiteNone } from 'should-send-same-site-none';

const app = express();
const PORT = process.env.PORT ?? '3000';

// Apply the middleware globally before defining routes.
// This middleware will automatically remove SameSite=None from 'Set-Cookie' headers
// if the requesting client is known to be incompatible.
app.use(shouldSendSameSiteNone);

app.get('/', (req, res) => {
  // When setting cross-site cookies, always set SameSite='None' and Secure=true.
  // The middleware will handle exceptions for incompatible browsers.
  res.cookie('session_id', 'somevalue123', { sameSite: 'none', secure: true, httpOnly: true });
  res.send('Hello World! Cookie set with SameSite=None; Secure (if compatible).');
});

app.listen(Number(PORT), () => {
  console.log(`Server listening on port ${PORT}`);
  console.log('Try visiting with an older Chrome browser (e.g., Chrome 51-66) to see the SameSite=None attribute removed.');
});