Cookies

Cookies in one minute

A cookie is a small piece of text that the browser saves for one website. It has a name and a value, written like theme=dark.

A few words first. A server is the computer that sends you a website. A request is a message the browser sends to a server, for example to get a page or an image. A header is a short line of extra information on a request or on the server's answer.

Here is what makes cookies special. The browser sends a saved cookie back to its website by itself, on every request that matches the cookie's rules. You don't write any code for that. Sites use this for:

• remembering that you are signed in,
• remembering your language,
• remembering whether you said yes to tracking.

Because cookies travel with requests, keep them small. Browsers allow about 4 KB (about 4,000 characters) per cookie, and the exact limit changes from browser to browser. Cookies are for short values, not for big data.

The table below lists four words you will meet in every section. Each row names one idea, says what it is, and says why it matters.

A cookie's lifetime is one of its rules. This code writes the same cookie two ways: one with an end date, one with a number of seconds.

const expires = new Date("2030-01-01T00:00:00Z").toUTCString();
const byDate = "session=short; Expires=" + expires + "; Path=/";
const bySeconds = "session=short; Max-Age=3600; Path=/";

console.log(byDate.includes("Expires="));
console.log(bySeconds.includes("Max-Age=3600"));

Line 2 uses Expires= with a date. Line 3 uses Max-Age=3600, which means 3,600 seconds (one hour) from now. Lines 5 and 6 both print true, because each string contains the rule we checked for. You will learn both rules in the lifetime section.

In the rest of this lesson you will write real test cookies on this site, read them back, try the SameSite rules, and learn when a cookie is the wrong place for your data.

In browser JavaScript, you reach cookies through document.cookie. It looks like a normal text property, but it does not work like one:

• Reading it gives one string with every cookie the page can see, like theme=dark; lang=en. A semicolon and a space separate the cookies.
• Writing to it sets, changes, or deletes one cookie. The other cookies stay as they were.
• Anything after the first semicolon in a write is a rule for that one cookie, not another cookie.
• HttpOnly cookies never show up in it.

1const value = encodeURIComponent("Ada; dark, 🍪");2document.cookie = "cf_demo_theme=" + value + "; Max-Age=600; Path=/; SameSite=Lax";3console.log(document.cookie);4document.cookie = "cf_demo_theme=; Max-Age=0; Path=/";

Try the starting value Ada; dark, 🍪. It has two problems for a cookie:

• The semicolon would end the value early, because a semicolon starts a rule.
• The emoji is not a plain letter or digit, so it may not travel safely.

So the playground first passes the value through encodeURIComponent. This built-in function swaps unsafe characters for safe codes, like a space for %20. When it reads the cookie back, it uses decodeURIComponent to turn the codes into the original text. Also notice what never comes back: Max-Age, Path, SameSite, and Secure.

function getCookie(cookieString, name) {
  const pair = cookieString.split("; ").find((item) => item.startsWith(encodeURIComponent(name) + "="));
  return pair ? decodeURIComponent(pair.split("=").slice(1).join("=")) : null;
}

function setCookie(name, value, options = {}) {
  const attributes = ["Path=/", "Max-Age=3600", "SameSite=Lax"];
  return encodeURIComponent(name) + "=" + encodeURIComponent(value) + "; " + attributes.join("; ");
}

const raw = "theme=dark; user=Ada%20Lovelace";
console.log(getCookie(raw, "user"));
console.log(setCookie("theme", "dark"));

getCookie splits the whole string into pairs. Then it finds the pair that starts with the name and an equals sign, and decodes only that value. If no pair matches, it returns null.

The part split("=").slice(1).join("=") needs a closer look. split("=") cuts the pair at every equals sign. slice(1) drops the first piece, which is the name. join("=") glues the rest back together. So a value that has its own equals sign stays whole.

setCookie does not save anything. It only builds the text for one write. In a real page you would assign that text to document.cookie.

const raw = "note=part=one; user=Ada%20Lovelace";
const userPair = raw.split("; ").find((pair) => pair.startsWith("user="));
const userValue = userPair?.split("=").slice(1).join("=") ?? "";

console.log(decodeURIComponent(userValue));
console.log(raw.includes("note=part=one"));

Here the note cookie has the value part=one, with its own equals sign. That is why a cookie reader must split each pair only at its first equals sign.

Line 3 uses two short tools. ?. (optional chaining) stops and gives undefined if userPair was not found, instead of throwing an error. ?? then swaps that undefined for an empty string, "".

The step-through below writes one cookie on line 1 and reads it back on line 3. This picture shows what goes in and what comes out.

1document.cookie = "theme=dark; Max-Age=3600; Path=/; SameSite=Lax";Run2 3const raw = document.cookie;4const parsed = raw.split("; ").map((pair) => pair.split("="));5console.log(raw);6console.log(parsed[0][0]);

A cookie with no Expires and no Max-Age is a session cookie. The browser may throw it away when you close the browser. To choose the lifetime yourself, add one of these rules. Each row of the table is one rule, with an example and what it does.

For Expires, the date must be in the format the web uses. date.toUTCString() gives you that format. If dates feel shaky, look back at the Date and time lesson. In most app code, Max-Age is easier, because it is just a number of seconds.

const appCookie = "theme=dark; Path=/app";
const deleteRoot = "theme=; Max-Age=0; Path=/";
const deleteApp = "theme=; Max-Age=0; Path=/app";

console.log(appCookie.includes("Path=/app"));
console.log(deleteRoot === deleteApp);

Line 1 is a cookie made for Path=/app. Lines 2 and 3 are two delete writes. They differ only in the path, but they point at different cookies. Line 6 prints false: the two writes are not the same. Only line 3 removes the /app cookie. In a real app, keep the code that creates a cookie next to the code that deletes it, so both use the same path.

Two pages are on the same site when they share the main web address, like www.example.com and shop.example.com. A request is cross-site when a page on a different site starts it, for example a link or a form on other.com that goes to example.com.

SameSite is a rule that says whether the browser sends the cookie on cross-site requests. It helps stop CSRF (cross-site request forgery). In CSRF, a bad site tries to make your browser send a request to a site where you are signed in. If your sign-in cookie goes along, the request looks like it came from you.

SameSite has three values:

• Strict: send the cookie only on same-site requests.
• Lax: send it on same-site requests, and also when you follow a normal link from another site. A normal link is a GET request that opens a whole new page. If a cookie has no SameSite rule, most browsers today treat it like Lax.
• None: send it on cross-site requests too. Browsers require Secure with it. Browsers may still block it in some cases, as you'll see below.

const requestCookie = "session=abc123";
const requestType = "cross-site image";

console.log(requestType + ": " + requestCookie);
console.log("Browser policy still decides whether it is sent");

This code only prints two lines. It shows the situation: an image from another site, and a cookie that could go with it. Whether the cookie is really sent is up to the browser, not your code.

A third-party cookie is a cookie for a site other than the one in the address bar. For example, a page on news.com shows an image from ads.com, and the request for the image carries an ads.com cookie. Browsers block or limit these more and more, mostly to stop tracking. SameSite=None; Secure is needed to allow them, but it does not promise that every browser will send the cookie.

Secure and HttpOnly do two different jobs:

• Secure: the browser sends the cookie only over HTTPS, the locked, encrypted kind of web address. Some browsers make an exception for localhost while you test, so in real apps think of Secure as "HTTPS only".
• HttpOnly: page JavaScript cannot read the cookie at all. It is still sent with requests.

A server sets these rules with a Set-Cookie header, one header per cookie. Here are two:

1Set-Cookie: session=abc123; Path=/; HttpOnly; Secure; SameSite=Lax2Set-Cookie: widget_id=public; Path=/; Secure; SameSite=None

Line 1 is a sign-in cookie, session. It has HttpOnly, so scripts can't read it. Line 2, widget_id, has no HttpOnly, so scripts can read it. It also has SameSite=None, so it can go with cross-site requests.

That is why sign-in cookies are usually set by the server, not by page code. With HttpOnly; Secure; SameSite=Lax, the browser keeps sending the sign-in cookie, and page scripts can't read it.

document.cookie is old and works with one string. It also answers right away, before the next line runs. The newer Cookie Store API works with promises instead. A promise is a value that arrives a little later; you wait for it with await. The API gives you:

• cookieStore.set to write a cookie,
• cookieStore.get and cookieStore.getAll to read cookies as objects,
• cookieStore.delete to remove one,
• a change event that tells you when a cookie changes.

It works only on HTTPS pages, and not every browser has it. So check first that it exists. This check is called feature detection. Run it in the browser after the page has loaded, because the server that builds the page has no window.

1if ("cookieStore" in window) {2  await cookieStore.set({ name: "cf_demo_store", value: "ready" });3  const cookie = await cookieStore.get("cf_demo_store");4  console.log(cookie.value);5  await cookieStore.delete("cf_demo_store");6}

The Cookie Store API is easier to use, but the cookies are the same. It still can't read HttpOnly cookies. The cookies are still small and still go with requests. Use it when the browser has it and you want promises or change events.

To decide, ask one question: does the server need this small value with each request?

• If yes, a cookie may fit.
• If only your JavaScript needs it, localStorage or sessionStorage (the next lesson) is often better.
• If the value is a real secret, keep it out of the browser.

const themeCookie = "theme=" + encodeURIComponent("dark")
  + "; Max-Age=31536000; Path=/; SameSite=Lax";

console.log(themeCookie);
// In a browser page: document.cookie = themeCookie;

A theme (light or dark colors) is a good cookie when the server must pick the colors for the very first page, before your JavaScript runs. The rules in this cookie:

• Max-Age=31536000 keeps it for one year, written in seconds.
• Path=/ sends it to every page of the site.
• SameSite=Lax keeps it off most cross-site requests.

If only your JavaScript reads the theme after the page loads, use localStorage instead. Then the theme is not sent with every request.

Common misconceptions

Key takeaways

• A cookie is a small name=value text that the browser saves and sends back to its site.
• Reading document.cookie gives all readable cookies as one string. Writing to it sets one cookie.
• Max-Age wins over Expires. To delete, write the cookie again with Max-Age=0 and the same name, path, and domain.
• SameSite decides whether the cookie goes with cross-site requests. None needs Secure.
• Secure means "send over HTTPS only". HttpOnly means "JavaScript can't read it".
• Check that the Cookie Store API exists before you use it, and keep a backup.

Final definition: a cookie is a small piece of text the browser saves for a site and sends back with matching requests. Its rules decide how long it lasts, where it goes, and who can read it. JavaScript can set some rules; only the server can set all of them.

Up next: localStorage and sessionStorage.