Cookies: document.cookie

Cookies são pequenos fragmentos de dados (máx. ~4 KB cada) que um site armazena no navegador e que são automaticamente enviados em toda requisição feita à mesma origem. Essa última característica é o que os diferencia de outros mecanismos de armazenamento no lado do cliente: os cookies viajam até o servidor, tornando-os o mecanismo clássico para identificadores de sessão, tokens de "lembre-se de mim" e preferências de idioma ou tema que o servidor precisa conhecer. Este guia aborda como ler, criar e excluir cookies com document.cookie, os atributos que controlam seu escopo e tempo de vida, e quando optar por outra opção de armazenamento.

Como o document.cookie funciona

document.cookie é uma propriedade enganosamente simples. Ao lê-la, ela retorna todos os cookies do documento atual como uma única string separada por ponto e vírgula, com pares name=value. Ao escrever nela, você define um cookie por vez — e, de forma importante, atribuir um valor a ela não sobrescreve toda a string. O navegador analisa sua atribuição e mescla esse único cookie ao conjunto existente:

// Reading: returns everything as one string
document.cookie; // "theme=dark; lang=en; sessionId=abc123"

// Writing: adds/updates ONE cookie, leaves the rest intact
document.cookie = "username=John";

Os atributos que você acrescenta (path, expires, Secure, …) são somente de escrita — eles configuram o cookie, mas nunca retornam quando você lê document.cookie. Você sempre obtém de volta apenas pares name=value.

Criando um cookie

Para criar um cookie, atribua uma string name=value a document.cookie, opcionalmente seguida de atributos separados por ;. Se o valor contiver espaços, ponto e vírgula ou outros caracteres especiais, codifique-o com encodeURIComponent para não quebrar a análise:

Isso cria um cookie chamado username com o valor John Doe (codificado para lidar com o espaço), expirando em 8 de junho de 2025 e acessível em todo o site (path=/).

Atributos de cookie

Os atributos são adicionados à string de atribuição e controlam para onde o cookie é enviado e por quanto tempo ele existe. Os mais importantes:

Sem expires ou max-age, você obtém um cookie de sessão que desaparece quando o navegador é fechado.

Definindo uma expiração

Use expires para uma data absoluta ou max-age para um tempo de vida relativo em segundos. max-age costuma ser mais fácil porque você não precisa formatar uma data:

Este cookie userSettings expira 24 horas (86.400 segundos) após ser criado.

Lendo um cookie específico

Como document.cookie retorna todos os cookies em uma única string, obter um valor específico requer análise. Um auxiliar robusto prefixa a string com ; para que a mesma divisão funcione tanto para o primeiro cookie quanto para qualquer outro:

Se precisar percorrer todos os cookies, divida por ; e analise cada par individualmente:

Excluindo um cookie

Não existe um comando "delete" — você exclui um cookie redefinindo-o com uma expiração no passado (ou max-age=0). O detalhe que pega todo mundo de surpresa: você deve usar o mesmo path e domain com que o cookie foi criado; caso contrário, o navegador o trata como um cookie diferente e mantém o original intacto.

Definir expires=Thu, 01 Jan 1970 00:00:00 UTC produz o mesmo resultado para navegadores que preferem expires em vez de max-age.

Protegendo cookies

Quando um cookie contém algo sensível (um token de sessão acima de tudo), os atributos importam tanto quanto o valor:

• Secure — envia o cookie somente via HTTPS, impedindo vazamentos por conexões HTTP simples.
• SameSite — controla se o cookie é anexado a requisições entre sites. Lax (o padrão moderno) o bloqueia na maioria das requisições entre sites, mitigando CSRF; Strict é o mais restritivo; None (que exige Secure) é para casos de uso genuinamente entre sites.
• HttpOnly — oculta o cookie do JavaScript por completo, protegendo tokens de sessão contra roubo por XSS. Não pode ser definido via document.cookie; o servidor deve enviá-lo pelo cabeçalho de resposta Set-Cookie. É por isso que cookies de sessão são tipicamente gerenciados pelo servidor.

document.cookie = "sessionId=abc123; expires=Sat, 08 Jun 2025 12:00:00 UTC; path=/; Secure; SameSite=Lax";

Cookies vs. localStorage

Cookies não são o único armazenamento no lado do cliente e, para a maioria dos dados, não são a melhor opção. Use cookies apenas quando o servidor precisar dos dados em cada requisição:

Se você só precisa lembrar algo no cliente e o servidor nunca lê esses dados, localStorage ou sessionStorage é mais simples e tem mais espaço; a Storage API cobre isso em profundidade. Como os cookies são enviados automaticamente com as requisições, eles também interagem com as regras de CORS — veja requisições entre origens com Fetch para enviar credenciais entre origens.

Conclusão

Cookies continuam sendo a forma padrão de compartilhar pequenos fragmentos de estado com o servidor — sessões, autenticação e preferências lidas pelo servidor. Escreva-os um de cada vez com document.cookie, delimite seu escopo com path/domain, controle seu tempo de vida com expires/max-age e proteja-os com Secure, SameSite e (no servidor) HttpOnly. Para dados maiores e exclusivos do cliente, prefira o Web Storage.

Prática