useCookies() for reading cookies without de-opting partial static rendering

[colinclerk]

Goals

1. Make cookies readable from client components deep in the tree without de-opting their parent components from static rendering

Non-Goals

1. Writing cookies

Background

There is currently no optimal way to read cookies from client components during SSR. Developers have two options:

1. Call cookies() from a parent server component and pass the value as a prop
2. Call cookies() from the root layout, set a context, and read cookies from the context. This is the technique used by next-client-cookies https://github.com/moshest/next-client-cookies/tree/main

The first technique offers reasonable cache behavior, but must be repeated any time a cookie is necessary for a client component.

The second technique does not require duplication, but needlessly de-opts the page from static rendering. It also represents a potential security issue, since HttpOnly cookies will be passed into the document body, potentially enabling javascript access to a value that is meant to only be accessed from the server.

Both techniques cause cookie data to needlessly be duplicated over the wire (cookies are already in a header, and passing them in a prop over the server/client boundary causes them to be duplicated in the document body)

Proposal

useCookies() should be implemented with the same cache behavior as useSearchParams(). So:

• If the client component is being dynamically rendered, cookie data should be available during the SSR run
• If the client component is statically rendered, rendering is suspended until cookie data is available on the client

During the SSR run, useCookies() should read from the Cookie header

On the client, useCookies() should read from document.cookie

Cookie values should not be included in the document body.