nookies

Nookies is a small, focused npm package that gives Next.js developers a single, consistent API for reading, writing, and clearing cookies regardless of where the code runs. Instead of hand-rolling separate cookie logic for getServerSideProps, API routes, custom Express servers, and client-side event handlers, nookies wraps the battle-tested cookie and set-cookie-parser packages behind three simple functions: parseCookies, setCookie, and destroyCookie.

The library’s main value is eliminating SSR/CSR cookie inconsistency: the same function signatures work whether a Next.js page context, an Express request/response pair, or no context at all (browser-only) is passed in. It has become a long-standing default in the Next.js ecosystem for session tokens, auth flows, and simple client preferences, and is frequently reached for anywhere authentication state needs to survive a server round-trip.

What You Get

• parseCookies(ctx, options) — reads cookies from a Next.js context, an Express request, or document.cookie in the browser, with the same call shape in every case
• setCookie(ctx, name, value, options) — writes a cookie via res.setHeader('Set-Cookie', ...) on the server or document.cookie in the browser, merging with any cookies already queued on the response instead of clobbering them
• destroyCookie(ctx, name, options) — a thin wrapper over setCookie that expires a cookie by name using the same context-aware logic
• A default export (nookies.get/set/destroy) alongside named exports, so it can be imported either as a namespace or as individual functions
• Full TypeScript typings shipped from source, including overloads for Next.js page/API contexts and Express request/response types
• Safe multi-cookie handling on the server: setCookie parses any existing Set-Cookie header entries with set-cookie-parser and avoids duplicating an equivalent cookie before appending the new one

Common Use Cases

• Storing an auth/session token from getServerSideProps so it’s available on both the first server render and subsequent client-side reads
• Reading and clearing an auth cookie inside a Next.js API route during login/logout handlers
• Setting cookies from a custom Express server wrapping a Next.js app, where the Express req/res objects are passed directly to nookies
• Persisting lightweight client-only preferences (e.g. a dismissed-banner flag) from a button click handler with no server context at all

Under The Hood

Architecture The published package (packages/nookies in a Yarn workspaces monorepo) is a flat two-file module: src/index.ts holds the public API (parseCookies, setCookie, destroyCookie, and a default export bundling all three), while src/utils.ts supplies stateless helpers (isBrowser, createCookie, hasSameProperties, areCookiesEqual). index.ts acts as a thin dispatcher that branches on whether a Next.js/Express req/res is present versus running in a browser (via isBrowser()), choosing between mutating response headers on the server and mutating document.cookie on the client. destroyCookie reuses setCookie with maxAge: -1 rather than duplicating expiry logic, and the duplicate-prevention helpers in utils.ts are the sole gate that keeps setCookie from appending a redundant Set-Cookie entry alongside an equivalent existing one. There is no internal state, dependency injection, or plugin system — every call is synchronous and side-effect-driven on the object passed in.

Tech Stack Runtime dependencies are minimal: cookie (^0.7.0) for serializing/parsing individual cookie strings and set-cookie-parser (^2.4.6) for parsing multiple existing Set-Cookie header entries on a response. next and express appear only as devDependencies, used exclusively for their TypeScript types to annotate the ctx parameter’s shape — neither is a runtime dependency. The workspace root uses Yarn 2 (Berry) workspaces spanning packages/* and examples/*, TypeScript 4.7.4 as the sole build tool (via shared g:tsc/g:prettier scripts), and husky + pretty-quick for pre-commit formatting. The package’s own build step runs tsc -d followed by terser to produce a minified dist/index.min.js alongside the unminified dist/index.js, both with source maps.

Code Quality No test files or test framework exist anywhere in the repository, and the single GitHub Actions workflow (Release) only builds and runs semantic-release on push to master — it does not run any test step. Naming is consistent and each exported function carries a JSDoc comment describing its ctx/options parameters. Typing is thorough: overloaded parameter types cover NextPageContext, NextApiRequest/NextApiResponse, and Express Request/Response so consumers get accurate autocomplete regardless of which framework they’re using nookies from. There is no linter config beyond Prettier’s formatting; without tests, regressions in the SSR duplicate-cookie logic would only surface at runtime.

What Makes It Unique Nookies isn’t architecturally novel — it’s a thin, well-typed convenience wrapper over cookie and set-cookie-parser — but its practical value is a single call signature that works unchanged across Next.js SSR contexts, Next.js API routes, custom Express servers, and plain browser code, removing the need for environment-specific cookie-handling branches that most Next.js apps would otherwise hand-roll themselves.