next-cookies

library2.0.3jsnpmunverified

Next Cookies is a focused utility library for Next.js applications, providing a straightforward method to read HTTP cookies on both the client and server sides. Currently at version 2.0.3, it offers a stable, minimalistic API centered around a single default export function that takes Next.js's `ctx` object (from `getInitialProps`) as an argument. Its primary differentiator is its simplicity and universal access pattern, allowing developers to consistently retrieve cookie values regardless of whether the page is rendered server-side or client-side. The package explicitly *does not* handle setting or deleting cookies, delegating these operations to native browser APIs like `document.cookie` or other specialized libraries. This clear separation of concerns makes it lightweight and easy to integrate for cookie *reading* tasks within the Next.js ecosystem. Given its mature state and narrow scope, it is likely in a maintenance cadence, receiving updates primarily for compatibility or critical bug fixes.

web-framework

npm install next-cookies

github ↗package ↗

INSTALL

IMPORT

SIG · NEXT-COOKIES

next-cookies

web-frameworkjavascriptv2.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import cookies from 'next-cookies'

✗ import { cookies } from 'next-cookies'

The 'cookies' function is the default export; use a default import.

cookies (CommonJS)

✓ const cookies = require('next-cookies')

✗ const { cookies } = require('next-cookies')

When using CommonJS, 'require' directly returns the default exported function.

TypeScript Types

✓ import cookies from 'next-cookies'; import type { NextPageContext } from 'next';

The library ships with TypeScript types. The 'ctx' object's type typically comes from 'next'.

This example demonstrates how to read cookies using `next-cookies` within Next.js's `getInitialProps` and how to set/delete them using native browser `document.cookie` API.

import React from 'react'; import cookies from 'next-cookies'; class NameForm extends React.Component { static async getInitialProps(ctx) { return { initialName: cookies(ctx).name || '' }; } constructor(props) { super(props); this.state = {name: props.initialName || ''}; this.handleChange = this.handleChange.bind(this); this.reset = this.reset.bind(this); } handleChange(event) { const newName = event.target.value; this.setState({name: newName}); document.cookie = `name=${newName}; path=/`; // Set cookie directly via browser API } reset() { this.setState({name: ''}); // Delete cookie directly via browser API by setting an past expiration date document.cookie = 'name=; path=/; expires=Thu, 01 Jan 1970 00:00:01 GMT'; } render() { return ( <div> <p>Hi {this.state.name}</p> <p>Change cookie: <input type="text" placeholder="Your name here" value={this.state.name} onChange={this.handleChange} />! </p> <p>Delete cookie: <button onClick={this.reset}>Reset</button></p> </div> ); } } export default NameForm;

Debug

Known issues

gotchaThis library is exclusively for reading cookies. It does not provide functionality for setting, updating, or deleting cookies. Developers must use native browser APIs (e.g., `document.cookie`) or other specialized libraries for these operations.

fix

To set a cookie client-side: `document.cookie = 'name=value; path=/';`. To delete a cookie client-side: `document.cookie = 'name=; path=/; expires=Thu, 01 Jan 1970 00:00:01 GMT';`. For server-side cookie management, use `res.setHeader('Set-Cookie', ...)` in API routes or `getServerSideProps`.

affects: >=1.0.0

gotchaThe primary API function `cookies(ctx)` relies on the `ctx` object, which is typically available only within Next.js's `getInitialProps` method or API routes. It is not designed for direct use in client-side React components without explicitly passing the context down.

fix

Ensure `cookies(ctx)` is called within `getInitialProps` or a Next.js API route. For client-side components, cookies must be read once in `getInitialProps` and passed as props, or accessed directly via `document.cookie`.

affects: >=1.0.0

gotchaAs Next.js evolves, particularly with the introduction of the App Router, the `getInitialProps` lifecycle method (which this library heavily relies on) is gradually being superseded by newer data fetching mechanisms like `getServerSideProps`, `getStaticProps`, or React Server Components. While still supported for the Pages Router, usage patterns might shift.

fix

Consider alternative cookie parsing methods if transitioning to the Next.js App Router, such as reading cookies directly from incoming request headers in server components or route handlers.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: next_cookies__WEBPACK_IMPORTED_MODULE_0__.cookies is not a function

Attempted to use a named import for 'cookies' instead of the default import, which is common in ESM.

fix

Change `import { cookies } from "next-cookies"` to `import cookies from "next-cookies"`.

ReferenceError: ctx is not defined

The `cookies(ctx)` function was called outside of a Next.js `getInitialProps` method or API route where the `ctx` object is provided.

fix

Ensure `cookies(ctx)` is invoked within the `static async getInitialProps(ctx)` method of a Next.js page component or inside a Next.js API route handler.

Cookie changes are not persisting or reflecting in the UI after next-cookies usage.

Misunderstanding that 'next-cookies' only reads cookies; it does not set or delete them. Changes made via `document.cookie` are not automatically reflected by `next-cookies` until a fresh read.

fix

Use native browser APIs like `document.cookie = 'key=value'` for setting cookies and `document.cookie = 'key=; expires=...'` for deleting them. Re-fetch cookies via `next-cookies` on subsequent requests/SSR cycles to see changes.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/matthewmueller/next-cookies ↗

packagehttps://www.npmjs.com/package/next-cookies ↗