Register for this year’s #ChromeDevSummit happening on Nov. 11-12 in San Francisco to learn about the latest features and tools coming to the Web. Request an invite on the Chrome Dev Summit 2019 website

Current status

How do I use the async cookie store?

Enable the origin trial

Note: We've temporarily ended the origin trial while we review your feedback
and use it to improve the API. Keep an eye out here for updates and
announcements about when we plan to re-open the origin trial.

To try it out locally, the API can be enabled on the command line:

chrome --enable-blink-features=CookieStore

Passing this flag on the command line enables the API globally in Chrome for
the current session.

Alternatively, you can enable the #enable-experimental-web-platform-features
flag in chrome://flags.

You (probably) don't need cookies

Before diving into the new API, I'd like to state that cookies are still the Web
platform's worst client-side storage primitive, and should still be used as a
last resort. This isn't an accident - cookies were the Web's first client-side
storage mechanism, and we've learned a lot since then.

The main reasons for avoiding cookies are:

Cookies bring your storage schema into the your back-end API.
Each HTTP request carries a snapshot of the cookie jar. This makes it easy for
back-end engineers to introduce dependencies on the current cookie format. Once
this happens, your front-end can't change its storage schema without deploying
a matching change to the back-end.

Cookies have a complex security model.
Modern Web platform features follow the same origin policy, meaning that
each application gets its own sandbox, and is completely independent from
other applications that the user might be running.
Cookie scopes
make for a significantly more complex security story, and merely attempting to
summarize that would double the size of this article.

Cookies have high performance costs. Browsers need to include a snapshot of
your cookies in every HTTP request, so every change to cookies must be
propagated across the storage and network stacks. Modern browsers have highly
optimized cookie store implementations, but we'll never be able to make
cookies as efficient as the other storage mechanisms, which don't need to talk
to the network stack.

For all the reasons above, modern Web applications should avoid cookies and
instead store a session identifier into
IndexedDB, and
explicitly add the identifier to the header or body of specific HTTP requests,
via the fetch API.

That being said, you're still reading this article because you have a good
reason to use cookies...

Reading a cookie, and eliminating jank

The venerable
document.cookie
API is a fairly guaranteed source of jank for your application. For example,
whenever you use the document.cookie getter, the browser has to stop executing
JavaScript until it has the cookie information you requested. This can take a
process hop or a disk read, and will cause your UI to jank.

A straightforward fix for this problem is switching from the document.cookie
getter to the asynchronous Cookie Store API.

The document.cookie setter can be replaced in a similar manner. Keep in mind
that the change is only guaranteed to be applied after the Promise returned by
cookieStore.set resolves.

await cookieStore.set({ name: 'opt_out', value: '1' });
// undefined

Observe, don't poll

A popular application for accessing cookies from JavaScript is detecting when
the user logs out, and updating the UI. This is currently done by polling
document.cookie, which introduces jank and has a negative impact on battery
life.

The Cookie Store API brings an alternative method for observing cookie
changes, which does not require polling.

However, observing cookie changes is a bit different in service worker. Waking
up a service worker can be pretty expensive, so we have to explicitly describe
the cookie changes that the worker is interested in.

In the example below, an application that uses IndexedDB to cache user data
monitors changes to the session cookie, and discards the cached data when the
user logs off.