Capítulo 01 / O que precisa estar instalado

Instalação

Três coisas precisam estar na sua máquina: Node.js 20+, Docker (para o stack do Supabase rodar localmente) e a CLI do Supabase. Em seguida, ESLint no editor.

Pré-requisitos

  • Node.js 20+ e npm — o projeto usa Next.js 16, então versões antigas não vão funcionar.
  • Docker rodando localmente — é o motor do Supabase local.
  • Git — provavelmente já tem.
  • Extensão ESLint instalada no seu editor.

Recomendado: Deno e Tailwind CSS IntelliSense como extensões do editor. Deno é útil para mexer nas edge functions (supabase/functions/); Tailwind acelera o trabalho de UI.

Docker

O Supabase local sobe ~10 containers via Docker Compose (Postgres, Auth, Storage, Realtime, Edge Runtime, Studio, Mailpit, etc.). Você não precisa entender de Docker — só precisa que ele esteja instalado e rodando.

Use o instalador oficial do Docker Desktop, ou via Homebrew:

brew install --cask docker

Depois abra o app uma vez para autorizar permissões e o daemon começar a rodar. Confirme com: 

docker info

Baixe o Docker Desktop para Windows e siga o instalador. Habilite a integração com WSL2 quando perguntado — é onde o projeto vai rodar de verdade.

Após instalar, abra o Docker Desktop pelo menu Iniciar uma vez. Ele precisa estar rodando (ícone na tray) sempre que você for usar o supabase start.

No WSL2, o caminho recomendado é instalar o Docker Desktop no Windows host e habilitar a integração com sua distro WSL nas configurações do Docker (Settings → Resources → WSL Integration). Assim o docker e o docker compose ficam disponíveis dentro do WSL sem instalação separada.

Confirme dentro do WSL:

docker --version && docker info | head

Em Linux nativo (Ubuntu/Debian/Fedora/Arch), instale o Docker Engine direto (não precisa do Desktop): 

# Ubuntu / Debian
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER  # logout e login depois disso

Para outras distros, siga as instruções oficiais. Confirme com docker info. Se aparecer "permission denied", é o passo do usermod que faltou.

Supabase CLI

A CLI do Supabase já é uma dev dependency do projeto, então npx supabase ... sempre funciona depois do npm install.

Mas como você vai usar muito, vale instalar globalmente para digitar só supabase. Atenção: a documentação oficial não suporta npm install -g supabase — use o gerenciador de pacotes do seu sistema.

Via Homebrew:

brew install supabase/tap/supabase

Confirme:

supabase --version

Via Scoop (no PowerShell):

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Se você nunca usou Scoop, instale primeiro com iwr -useb get.scoop.sh | iex em um PowerShell sem privilégios elevados.

Baixe o pacote correspondente na página de releases da CLI: .deb (Debian/Ubuntu), .rpm (Fedora/RHEL), .apk (Alpine) ou .pkg.tar.zst (Arch). Exemplo Debian: 

wget https://github.com/supabase/cli/releases/download/v2.x.x/supabase_2.x.x_linux_amd64.deb
sudo dpkg -i supabase_*.deb
Atalho útil

Se você não quer instalar globalmente, está tudo bem — basta sempre prefixar com npx. Os scripts npm do projeto (como npm run db:reset) já chamam a CLI internamente, então o uso direto é raro no dia a dia.

Node.js

Versão mínima: 20. Use o gerenciador da sua preferência. Recomendados:

  • fnm (rápido, multiplataforma, brew install fnm ou winget install fnm).
  • nvm (clássico, mais difundido em macOS/Linux).
  • Instalador oficial em nodejs.org.

Confirme:

node --version  # >= 20

Verificação final

Depois de tudo, este check rápido deve passar limpo:

node --version       # v20+
docker info          # daemon rodando
supabase --version   # ou npx supabase --version
git --version
Próximo passo

Com tudo instalado, siga para o capítulo seguinte para clonar o projeto, subir o stack e fazer o primeiro login.