Gerando IDs Únicos com a Web Crypto API

Todo desenvolvedor frontend eventualmente enfrenta este problema: você precisa de um identificador único para dados do lado do cliente, mas ainda não há um ID gerado pelo servidor. Talvez você esteja construindo uma lista de tarefas, gerenciando campos de formulário ou rastreando itens antes de serem persistidos. Você precisa de algo confiável, e precisa agora.

A boa notícia? Os navegadores modernos vêm com uma solução integrada. A Web Crypto API fornece crypto.randomUUID()—uma maneira simples e segura de gerar IDs únicos no navegador sem instalar nenhuma biblioteca.

Por Que crypto.randomUUID() Deve Ser Sua Opção Padrão

O método crypto.randomUUID() produz UUIDs versão 4 conforme RFC 9562 (anteriormente RFC 4122) usando um gerador de números aleatórios criptograficamente seguro. A saída se parece com isto:

550e8400-e29b-41d4-a716-446655440000

Isso é uma string de 36 caracteres com 122 bits de aleatoriedade. A probabilidade de colisão é astronomicamente baixa—você precisaria gerar um bilhão de UUIDs por segundo durante cerca de 85 anos para atingir uma chance de 50% de uma única colisão.

Veja como é simples:

function generateId() {
  return crypto.randomUUID()
}

const newItem = { id: generateId(), label: 'My item' }

Este método funciona em todos os navegadores modernos (Chrome 92+, Firefox 95+, Safari 15.4+), executa em Web Workers e não requer dependências.

O Requisito de Contexto Seguro

Um detalhe crítico: crypto.randomUUID() funciona apenas em contextos seguros. Isso significa HTTPS em produção ou localhost durante o desenvolvimento. Se você estiver testando via HTTP simples em um domínio que não seja localhost, o método não estará disponível.

Este requisito existe porque a Web Crypto API fornece primitivas criptográficas que não devem ser expostas em ambientes inseguros.

Por Que Padrões Antigos Ficam Aquém

Antes de crypto.randomUUID() se tornar amplamente disponível, desenvolvedores frequentemente recorriam a alternativas que parecem razoáveis mas têm problemas reais.

Math.random() não é criptograficamente seguro. Sua saída pode ser previsível, e colisões são muito mais prováveis do que você esperaria em aplicações de produção.

Timestamps (como Date.now()) falham quando múltiplos IDs são gerados no mesmo milissegundo—um cenário comum em loops ou operações em lote.

Geradores ad-hoc combinando timestamps com números aleatórios são melhores, mas estão reinventando um problema resolvido com menos rigor do que a plataforma fornece nativamente.

Para geração segura de IDs do lado do cliente, crypto.randomUUID() é a escolha clara.

Considerações Práticas de Frontend

Gere Uma Vez, Armazene Imediatamente

O erro mais comum é gerar IDs durante ciclos de renderização. Em vez disso, crie o ID quando o objeto for criado e armazene-o:

// ✓ Correto: ID gerado no momento da criação
function addItem(label) {
  return { id: crypto.randomUUID(), label }
}

// ✗ Errado: ID gerado durante renderização
items.map(item => <li key={crypto.randomUUID()}>{item.label}</li>)

Gerar um novo UUID a cada renderização derrota o propósito de chaves estáveis. React, por exemplo, usa chaves para rastrear elementos através de re-renderizações. Uma nova chave a cada vez força desmontagem e recriação desnecessária do DOM.

SSR e Ambientes de Navegador

Se você está usando renderização do lado do servidor, crypto.randomUUID() está disponível no Node.js 19+ e versões recentes de outros runtimes. Para versões mais antigas do Node ou casos extremos, verifique a disponibilidade antes de chamar:

const id = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
  ? crypto.randomUUID()
  : fallbackGenerator()

Uma Estratégia de Fallback Leve

Para ambientes onde crypto.randomUUID() não está disponível, crypto.getRandomValues() tem suporte mais amplo (incluindo Node.js 16+) e pode gerar UUIDs sem bibliotecas:

function fallbackUUID() {
  const bytes = crypto.getRandomValues(new Uint8Array(16))
  bytes[6] = (bytes[6] & 0x0f) | 0x40 // Version 4
  bytes[8] = (bytes[8] & 0x3f) | 0x80 // Variant 10
  
  const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('')
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
}

Isso define manualmente os bits de versão e variante para produzir um UUID v4 válido, usando a mesma fonte aleatória criptograficamente segura por baixo dos panos.

Quando Bibliotecas Ainda Fazem Sentido

Embora crypto.randomUUID() cubra a maioria dos casos, você pode recorrer a uma biblioteca como uuid ou nanoid quando precisar de:

• Versões de UUID não-v4 (v1, v5, v7)
• IDs mais curtos para URLs ou exibições voltadas ao usuário
• Compatibilidade garantida entre ambientes com runtimes mais antigos

Mas para geração padrão de IDs seguros do lado do cliente, a API nativa deve ser seu ponto de partida.

Conclusão

crypto.randomUUID() fornece UUIDs criptograficamente seguros e compatíveis com RFC com zero dependências. Gere IDs no momento da criação do objeto, não durante renderizações. Use HTTPS em produção. Para casos extremos, recorra a crypto.getRandomValues(). O navegador já tem o que você precisa—use-o.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.