@yaredfall/react-cookies
v0.0.3
Published
Simple client-side cookie management for React
Readme
@yaredfall/react-cookies
Simple client-side cookie management for React
Features
- Type-safe: Full TypeScript support
- Lightweight: Minimal api with no bloat
- Shared storage: All consumers get notified when a cookie is set or removed
- Syncronization: External cookie changes are picked up automatically
- Automatic serialization: Built-in JSON parsing and stringification
- SSR support: Works with Next.js and other React frameworks
Installation
npm add @yaredfall/react-cookiesQuick Start
Wrap your app with CookiesProvider
import { CookiesProvider } from "@yaredfall/react-cookies";
function App({ children }: { children: React.ReactNode }) {
return (
<CookiesProvider path="/">
{children}
</CookiesProvider>
);
}Use the useCookie hook to read and write cookies
import { useCookie } from "@yaredfall/react-cookies";
function CookieDemo() {
const [cookie, setCookie, removeCookie] = useCookie("test", "default value", { maxAge: 60 });
return (
<div>
<p>Cookie: {cookie}</p>
<button onClick={() => setCookie("new value")}>Set cookie</button>
<button onClick={() => removeCookie()}>Remove cookie</button>
</div>
);
}API
<CookiesProvider />
Provides the cookie store to the app.
Props:
pollingInterval- polling interval in ms to pick up external cookie changes (default: 1000)initialCookieString- initial cookie string. Use it to provide cookie header during server-side renderingdomain- default domain attribute of cookie setterexpires- default expires attribute of cookie settermaxAge- default max-age attribute of cookie setterpartitioned- default partitioned attribute of cookie setterpath- default path attribute of cookie settersameSite- default same-site attribute of cookie settersecure- secure attribute of the cookieparse- default function to parse the cookie valuestringify- default function to stringify the cookie value
useCookie<T>(name, defaultValue, options)
name - name of the cookie
defaultValue - value to return if the cookie is not defined
options - (optional) Options to control cookie behavior. The object can have the following properties
domain- domain attribute of the cookieexpires- expires attribute of the cookiemaxAge- max-age attribute of the cookiepartitioned- partitioned attribute of the cookiepath- path attribute of the cookiesameSite- same-site attribute of the cookiesecure- secure attribute of the cookieparse- function to parse the cookie valuestringify- function to stringify the cookie value
Returns a tuple [value, set, remove] where:
valueis the current cookie value or the default value if not undefinedset(value)sets the cookie value with the provided optionsremove()removes the cookie with the provided options
By default, the cookie value is parsed and stringified as a JSON string. You can override this by providing custom parse and stringify functions.
SSR
To provide cookies during server-side rendering, set the initialCookieString prop of CookiesProvider to the cookie header value.
Example with Next.js 15+:
import { CookiesProvider } from "@yaredfall/react-cookies";
import { headers } from "next/headers";
export default async function Layout({ children }: Readonly<{ children: React.ReactNode }>) {
const headerList = await headers();
return (
<html lang="en">
<body>
<CookiesProvider initialCookieString={headerList.get("cookie")}>
{children}
</CookiesProvider>
</body>
</html>
);
}