Instalar Sass e compilar o primeiro SCSS com npx

Você precisa de duas coisas para esta lição: Node instalado e um terminal aberto na pasta do projeto. Não vamos instalar Sass no sistema inteiro. O primeiro comando usa npx, que executa o pacote solicitado, e o segundo fixa a ferramenta no projeto quando a experiência deixar de ser descartável.

Na máquina de teste, node --version devolveu v26.3.0. Confira a sua antes de culpar o SCSS por um problema de ambiente:

node --version
npx --yes sass@1.103.1 --version

Se o conceito de compilação ainda estiver abstrato, leia o que é Sass. Aqui vamos acompanhar cada arquivo que entra e sai do comando.

O que o compilador faz com o seu arquivo

Crie a.scss. A variável e o seletor aninhado são instruções para o Sass; o navegador não deve receber nenhum dos dois desse jeito:

$brand: #6d28d9;

.button {
  background: $brand;
  color: white;
}

Agora transforme a entrada em CSS:

npx sass a.scss a.css

Quando recebe um arquivo de destino, o comando termina silenciosamente em caso de sucesso. Depois do status 0, o conteúdo gravado em a.css foi:

O compilador leu a.scss, substituiu $brand, gravou a.css e também criou a.css.map. O HTML aponta apenas para o resultado, como ensina a aula de incluir CSS no HTML.

Rodar sem instalar: npx sass em um comando

npx sass é ótimo para uma prova rápida porque não exige uma instalação global. Para tornar a versão reproduzível, escreva-a no comando:

npx --yes sass@1.103.1 a.scss a.css --style=expanded

O terminal não imprimiu uma mensagem de sucesso. O processo devolveu status 0, e a existência de a.css e a.css.map confirmou os dois artefatos gravados.

O --yes evita a pergunta de confirmação quando o pacote ainda não está no cache. Ele não significa “ignore erros”. Se o código for inválido, o status continua diferente de zero.

No teste desta página, /usr/bin/time -p mediu 1.06 s para um comando via npx com o pacote já disponível. Esse número descreve a máquina e o cache daquele momento; não é promessa de desempenho para outro computador.

/usr/bin/time -p npx --yes sass@1.103.1 a.scss a.css

O CSS que sai, incluindo a linha que você não escreveu

A última linha de a.css aponta para o sourcemap. Para produzir um arquivo sem esse comentário e sem o .map, use --no-source-map:

npx sass a.scss a.css --no-source-map

O comando também ficou silencioso. Abrindo o novo a.css, a saída gravada foi:

Também existe --style=compressed, útil quando o próprio Sass gera o artefato de produção. Durante a aula, mantenha expanded: ler o CSS final é parte do aprendizado, não um detalhe descartável.

--watch: recompilar a cada Ctrl+S

No desenvolvimento, repetir o comando após toda edição é desperdício. O modo watch mantém o processo aberto e recompila quando o arquivo muda:

npx sass --watch main.scss:main.css

Depois que uma declaração color: white foi salva, o processo imprimiu uma segunda linha Compiled main.scss to main.css.. O horário é real da execução, mas naturalmente será outro no seu terminal. A sintaxe com dois-pontos liga uma entrada a uma saída; também é possível observar uma pasta inteira.

npx sass --watch src/scss:public/css

O sourcemap e por que o DevTools mostra o .scss

Abra a.css.map e você verá JSON. No teste, o campo sources guardou a.scss, e file apontou para a.css:

{"version":3,"sourceRoot":"","sources":["a.scss"],"names":[],"mappings":"AAEA;EACE,YAHM;EAIN","file":"a.css"}

Lendo o JSON, sources[0] vale a.scss e file vale a.css.

O navegador usa esse mapa para relacionar uma regra compilada à linha original. Por isso o DevTools pode mostrar a.scss:4 mesmo tendo baixado a.css. Em produção, manter ou remover sourcemaps é uma decisão de observabilidade e exposição do fonte, não uma exigência da linguagem.

Instalar no projeto: devDependency e script npm

Quando o projeto continuar existindo depois do exercício, fixe Sass em devDependencies. Assim, o lockfile registra a resolução e o CI usa a mesma família de versão:

npm install --save-dev sass@1.103.1
npm pkg set scripts.css="sass --watch src/scss:public/css"
npm run css

Os dois primeiros comandos alteram package.json e o lockfile; a quantidade de linhas impressas pelo npm depende do projeto. O terceiro inicia o watcher e permanece aberto até Ctrl+C, sem um status final de sucesso enquanto observa.

Evite npm install -g sass como padrão de equipe. A instalação global pode estar numa versão em cada notebook, enquanto a dependência local via script é descoberta automaticamente pelo npm.

SCSS ou .sass indentado: a mesma linguagem, duas escritas

O compilador escolhe a sintaxe pela extensão. Este arquivo card.sass não usa chaves nem ponto e vírgula:

.card
  padding: 1rem
  &__title
    color: #6d28d9

npx sass card.sass card.css --no-source-map

Em projeto novo, escolha .scss: todo CSS válido já é SCSS válido, e a transição mental é menor. Em legado, respeite a extensão existente antes de formatar o arquivo.

Quando o compilador para: o primeiro erro de sintaxe

Remova a chave final de .button e execute novamente. O Sass devolve status 65, desenha a coluna com um acento e não produz uma folha válida:

$brand: #6d28d9;

.button {
  background: $brand;

Leia de baixo para cima: arquivo e posição, trecho, marcador e mensagem. O marcador está no fim da linha porque o parser chegou ali ainda esperando o fechamento do bloco.

Onde guardar o CSS gerado (e por que ele não vai pro Git)

Uma estrutura pequena pode separar fonte e artefato: src/scss/main.scss entra, public/css/main.css sai. Se o deploy executa npm ci e npm run build, o CSS gerado é reproduzível e normalmente fica no .gitignore:

public/css/
*.css.map

Com essas entradas, o Git passa a versionar o SCSS e o lockfile, não o resultado reproduzível.

Há uma exceção legítima: um site sem etapa de build precisa receber o CSS pronto. Nesse caso, versione a saída e documente o comando que a atualiza. O importante é não deixar dois arquivos que podem divergir sem uma regra clara.

Com o compilador funcionando, avance para variáveis no Sass. O guia de Sass mostra onde instalação, fundamentos e módulos se encaixam na trilha completa.