---
title: "Cookie Jar Plugin"
description: "Store the cookies servers set and send them back on later requests, like a browser, for server-side clients."
sidebar:
  label: "Cookie Jar"
---

Clients outside a browser, such as during server-side rendering, in scripts, or in tests, do not keep cookies. `CookieJarLinkPlugin` stores the cookies servers set and sends them back on later requests, following the browser rules of [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265).

## Setup

```ts
import { CookieJarLinkPlugin } from '@orpc/client/plugins'

const origin = 'https://api.example.com'

const link = new RPCLink({
  origin,
  plugins: [
    new CookieJarLinkPlugin({ origin }), // <- same origin as the link
  ],
})
```

The plugin does nothing when `origin` is `undefined` or relative, as in a browser, which handles cookies itself. A `cookie` header you set, such as through the link's `headers` option, wins over jar cookies with the same name.

:::info
The `link` can be any supported oRPC link, such as [RPCLink](/docs/rpc/link), [OpenAPILink](/docs/openapi/link), or a custom one.
:::

:::warning
On a server, do not share a link between users, or one user's cookies are sent with another's calls. Create a client per request, or use a [per-request jar](#per-request-jar).
:::

## Custom Jar

Pass your own `CookieJar` to read, clear, or share cookies between links:

```ts
import { CookieJar, CookieJarLinkPlugin } from '@orpc/client/plugins'

const jar = new CookieJar()

const link = new RPCLink({
  origin,
  plugins: [new CookieJarLinkPlugin({ origin, jar })],
})

jar.getCookies() // <- stored cookies
jar.clear()
```

The jar has no public suffix list, so a site could set a cookie for all of `.com`. Only share a jar between sites you trust.

## Per-Request Jar

`jar` also accepts a function, so one link can keep a jar per user:

```ts
const link = new RPCLink<{ jar: CookieJar }>({
  origin,
  plugins: [
    new CookieJarLinkPlugin({
      origin,
      jar: ({ context }) => context.jar,
    }),
  ],
})
```

:::warning
With the [Batch Plugin](/docs/plugins/batch), a batch response carries the cookies of all its calls, so keep users in separate batches with [`scope`](/docs/plugins/batch#scope).
:::

## Learn More

For implementation details, see the [CookieJarLinkPlugin source code](https://github.com/middleapi/orpc/blob/main/packages/client/src/plugins/cookie-jar.ts).