Sharp para JavaScript (Node.js): guia completo com exemplos

Introdução: O que é Sharp e para que serve?

\n\n

Sharp é uma biblioteca de alto desempenho para processamento de imagens, escrita em C++ e que fornece uma API conveniente para Node.js. Ela permite converter imagens nos formatos JPEG, PNG, WebP, AVIF, TIFF e GIF para outros formatos, redimensionar, cortar, girar, adicionar efeitos e muito mais.

\n\n

A principal vantagem do Sharp é a velocidade. A biblioteca utiliza as bibliotecas nativas libvips, tornando-a várias vezes mais rápida que alternativas (como Jimp ou gm). É ideal para:

\n

\n
• Servidores web e APIs — processamento dinâmico de avatares, pré-visualizações, otimização de imagens antes do upload.
\n
• Processamento em lote — conversão de milhares de imagens para o formato e tamanho desejados.
\n
• Criação de miniaturas e galerias — geração rápida de thumbnails.
\n
• Otimização do peso das imagens — compressão sem perda de qualidade (ou com perda controlada).
\n

\n\n

Sharp trabalha com buffers, streams e arquivos, tornando-a flexível para integração em qualquer aplicação Node.js.

\n\n

Instalação

\n\n

A instalação do Sharp é feita via npm. A biblioteca requer Node.js versão 12.13.0 ou superior (recomendado 14+).

\n\n

npm install sharp

\n\n

Se você usa yarn:

\n\n

yarn add sharp

\n\n

Importante: O Sharp compila módulos nativos durante a instalação. Se você encontrar erros, certifique-se de que o build-essential (no Linux) ou o Xcode Command Line Tools (no macOS) estão instalados. Para Windows, geralmente é suficiente ter o Visual Studio Build Tools.

\n\n

Após a instalação, importe a biblioteca no seu projeto:

\n\n

const sharp = require('sharp');

\n\n

Início rápido

\n\n

Vamos escrever um script simples que carrega uma imagem, a reduz para 300 pixels de largura (mantendo a proporção) e a salva no formato WebP.

\n\n

const sharp = require('sharp');\nconst path = require('path');\n\nasync function quickStart() {\n    try {\n        await sharp('input.jpg')\n            .resize(300) // Largura 300px, altura ajustada automaticamente\n            .webp({ quality: 80 }) // Converte para WebP com qualidade 80%\n            .toFile('output.webp');\n        \n        console.log('Imagem processada com sucesso!');\n    } catch (error) {\n        console.error('Erro:', error);\n    }\n}\n\nquickStart();

\n\n

Este exemplo demonstra o encadeamento de métodos (chaining), que é a base do trabalho com Sharp. Cada método retorna uma nova instância do Sharp, permitindo aplicar transformações sequencialmente.

\n\n

Métodos e funções principais

\n\n

Abaixo estão 10 métodos-chave do Sharp com descrição detalhada, parâmetros e exemplos de código.

\n\n

1. resize() — Redimensionamento de imagem

\n

O que faz: Altera a largura e/ou altura da imagem. Pode cortar ou ajustar a imagem dentro de limites definidos.

\n

Parâmetros:

\n

\n
• width (number, opcional) — nova largura em pixels.
\n
• height (number, opcional) — nova altura em pixels.
\n
• options (object, opcional):\n
  \n
  • fit (string) — modo de ajuste: 'cover' (preencher, cortando o excesso), 'contain' (ajustar completamente), 'fill' (esticar), 'inside' (reduzir para caber), 'outside' (aumentar até ultrapassar os limites). Padrão: 'cover'.
  \n
  • position (string) — posição ao cortar: 'center', 'top', 'left', 'right', 'bottom', etc.
  \n
  • withoutEnlargement (boolean) — proibir o aumento da imagem.
  \n
  \n
\n

\n

Exemplo:

\n

// Reduzir para 200x200, cortando pelo centro\nawait sharp