Executando Scripts Personalizados com NPM

Olá, futuro(a) desenvolvedor(a) Node.js! 👋 Nesta aula prática, vamos mergulhar no mundo dos npm scripts, uma ferramenta incrivelmente poderosa para automatizar tarefas e padronizar fluxos de trabalho em seus projetos Node.js.

1. Introdução: O Poder dos npm scripts ✨

Você já se perguntou como os projetos Node.js conseguem executar comandos complexos como "iniciar o servidor", "rodar testes" ou "compilar o código" com apenas um comando simples como npm start ou npm test? A resposta está nos npm scripts!

Os npm scripts são entradas personalizadas no arquivo package.json que mapeiam nomes de comandos curtos para comandos de shell mais longos e complexos. Eles são essenciais para:

• Automação: Execute sequências de comandos complexas com facilidade.
• Padronização: Garanta que todos os desenvolvedores em um projeto usem os mesmos comandos para as mesmas tarefas.
• Produtividade: Economize tempo digitando comandos longos e propensos a erros.
• Portabilidade: Seus scripts funcionam em diferentes ambientes (Windows, macOS, Linux) sem grandes modificações, desde que os comandos subjacentes sejam compatíveis ou você use ferramentas como cross-env.

Vamos explorar como definir, executar e otimizar esses scripts!

2. Entendendo e Executando Scripts Personalizados ⚙️

O coração dos npm scripts reside no objeto "scripts" dentro do seu arquivo package.json.

2.1. A Estrutura do package.json para Scripts

Abra seu arquivo package.json. Você provavelmente verá uma seção como esta:

{
  "name": "meu-projeto-node",
  "version": "1.0.0",
  "description": "Um projeto de exemplo para npm scripts.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

O objeto "scripts" é onde você define seus comandos. Cada propriedade dentro de "scripts" é um nome de script, e seu valor é o comando de shell que será executado.

2.2. Executando Scripts Básicos

Para executar um script, você usa o comando npm run <nome-do-script>.

Por exemplo, para executar o script test padrão:

npm run test

Você verá a saída:

> meu-projeto-node@1.0.0 test
> echo "Error: no test specified" && exit 1

"Error: no test specified"

2.3. Scripts Padrão (e suas "atalhos")

Alguns scripts têm atalhos especiais e não precisam do prefixo run:

• start: Usado para iniciar o aplicativo principal.
  • npm start (equivalente a npm run start)
• test: Usado para executar testes.
  • npm test (equivalente a npm run test)
• install: Executado após npm install.
  • npm install (equivalente a npm run install)

2.4. Criando Seus Próprios Scripts Personalizados

Vamos adicionar um script simples para dizer "Olá":

// package.json
{
  "name": "meu-projeto-node",
  "version": "1.0.0",
  "description": "Um projeto de exemplo para npm scripts.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "hello": "echo \"Olá, Mundo dos npm scripts!\""
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Agora, execute-o:

npm run hello

Saída:

> meu-projeto-node@1.0.0 hello
> echo "Olá, Mundo dos npm scripts!"

Olá, Mundo dos npm scripts!

2.5. Executando Binários Locais 📦

Uma das características mais úteis dos npm scripts é que eles automaticamente adicionam o diretório node_modules/.bin ao PATH do shell quando executados. Isso significa que você pode usar ferramentas CLI instaladas localmente (como nodemon, eslint, mocha, etc.) diretamente nos seus scripts, sem precisar instalá-las globalmente.

Vamos instalar o nodemon como uma dependência de desenvolvimento para ver isso em ação:

npm install nodemon --save-dev

Crie um arquivo index.js simples:

// index.js
console.log('Servidor Node.js iniciado!');
let counter = 0;
setInterval(() => {
  counter++;
  console.log(`Contador: ${counter}`);
}, 1000);

Agora, adicione um script para rodar index.js com nodemon:

// package.json
{
  "name": "meu-projeto-node",
  // ...
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "hello": "echo \"Olá, Mundo dos npm scripts!\"",
    "dev": "nodemon index.js"
  },
  // ...
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Execute o script dev:

npm run dev

Você verá o nodemon iniciando seu arquivo index.js e reiniciando-o automaticamente se você fizer alterações.

2.6. Passando Argumentos para Scripts ➡️

Você pode passar argumentos diretamente para seus scripts usando -- após o nome do script. Tudo o que vier depois de -- será passado como argumentos para o comando subjacente.

Exemplo:

// package.json
{
  // ...
  "scripts": {
    "greet": "echo Olá, $1!"
  },
  // ...
}

Nota para Windows: No Windows, $1 pode não funcionar como esperado. Uma alternativa mais robusta para scripts que precisam de argumentos variáveis é usar um script Node.js intermediário ou uma ferramenta como yargs dentro de um script Node.js. Para scripts simples como este, $1 pode ser substituído por %* (para todos os argumentos) ou %1 (para o primeiro argumento) em cmd.exe, mas a compatibilidade entre shells é um desafio. Para fins desta aula, focaremos no comportamento mais comum em ambientes Unix-like.

Execute:

npm run greet -- "João"

Saída (em sistemas Unix-like):

> meu-projeto-node@1.0.0 greet
> echo Olá, João!

Olá, João!

2.7. Encadear Scripts (Sequencial e Paralelo) 🔗

Você pode encadear vários comandos em um único script:

• Sequencial (&&): O próximo comando só executa se o anterior for bem-sucedido.
• Paralelo (&): Todos os comandos são executados simultaneamente.

// package.json
{
  // ...
  "scripts": {
    "clean": "rm -rf dist",
    "build:js": "echo 'Compilando JavaScript...' && sleep 1 && echo 'JavaScript compilado.'",
    "build:css": "echo 'Compilando CSS...' && sleep 2 && echo 'CSS compilado.'",
    "build": "npm run clean && npm run build:js && npm run build:css",
    "dev:parallel": "npm run build:js & npm run build:css"
  },
  // ...
}

Nota para Windows: rm -rf é um comando Unix-like. Para compatibilidade cross-platform, você pode usar a biblioteca rimraf (npm install rimraf --save-dev) e usar rimraf dist em vez de rm -rf dist. O sleep também é Unix-like; em Windows, use timeout /t 1 ou um script Node.js. Para simplicidade, manteremos os comandos Unix-like, mas lembre-se das implicações de plataforma. Para execução paralela em Windows, & pode ter comportamentos ligeiramente diferentes; ferramentas como concurrently são recomendadas para projetos maiores.

Execute:

npm run build
# Limpa, compila JS, depois compila CSS
 
npm run dev:parallel
# Compila JS e CSS ao mesmo tempo

2.8. Hooks pre e post 🎣

O NPM oferece hooks pre e post para scripts. Se você definir um script chamado myscript, o NPM procurará e executará automaticamente prescript antes de myscript e postscript depois de myscript.

Exemplo:

// package.json
{
  // ...
  "scripts": {
    "predeploy": "echo 'Verificando antes do deploy...'",
    "deploy": "echo 'Realizando deploy da aplicação...'",
    "postdeploy": "echo 'Deploy concluído!'"
  },
  // ...
}

Execute:

npm run deploy

Saída:

> meu-projeto-node@1.0.0 predeploy
> echo 'Verificando antes do deploy...'
'Verificando antes do deploy...'

> meu-projeto-node@1.0.0 deploy
> echo 'Realizando deploy da aplicação...'
'Realizando deploy da aplicação...'

> meu-projeto-node@1.0.0 postdeploy
> echo 'Deploy concluído!'
'Deploy concluído!'

2.9. Variáveis de Ambiente 🌍

Você pode definir variáveis de ambiente dentro de seus scripts. Isso é útil para configurar o ambiente de execução (ex: NODE_ENV=production).

// package.json
{
  // ...
  "scripts": {
    "start:prod": "NODE_ENV=production node index.js"
  },
  // ...
}

Nota para Windows: NODE_ENV=production é um comando Unix-like. Para compatibilidade cross-platform, use a biblioteca cross-env (npm install cross-env --save-dev). Com cross-env, o script ficaria assim: "start:prod": "cross-env NODE_ENV=production node index.js".

No seu index.js, você pode acessá-lo:

// index.js
console.log('Ambiente:', process.env.NODE_ENV || 'development');
// ... (seu código do servidor)

Execute:

npm run start:prod

Saída:

> meu-projeto-node@1.0.0 start:prod
> NODE_ENV=production node index.js

Ambiente: production
Servidor Node.js iniciado!
Contador: 1
...

3. Exercícios Práticos 🚀

É hora de colocar a mão na massa! Crie um novo diretório para esta aula e inicialize um projeto Node.js (npm init -y).

Tarefa 1: Configuração Inicial

Crie um novo projeto Node.js e adicione os seguintes scripts ao seu package.json:

• "start": Um script que executa um arquivo app.js (que você criará).
• "test": Mantenha o script padrão de teste.
• "hello": Um script que exibe "Olá do meu primeiro script NPM!".

Passos:

1. Crie um diretório npm-scripts-aula.
2. Navegue até ele: cd npm-scripts-aula.
3. Inicialize o projeto: npm init -y.
4. Crie um arquivo app.js com o seguinte conteúdo:

   // app.js
   console.log('Aplicação Node.js iniciada!');

5. Modifique seu package.json para incluir os scripts acima.

Tarefa 2: Usando Binários Locais

Instale o eslint como uma dependência de desenvolvimento e crie um script para lintar seu código.

Passos:

1. Instale eslint: npm install eslint --save-dev.
2. Crie um arquivo de configuração eslint padrão: npx eslint --init. (Escolha as opções que preferir, como "To check syntax, find problems, and enforce code style" e "JavaScript modules (import/export)").
3. Crie um arquivo src/index.js com algum código que tenha erros de lint (ex: variáveis não usadas, ponto e vírgula faltando).
4. Adicione um script "lint" ao seu package.json que execute eslint src/**/*.js.
5. Execute npm run lint e observe a saída.

Tarefa 3: Encadeando Scripts e Hooks

Crie um script build que limpa um diretório dist e depois "compila" alguns arquivos. Use hooks pre e post.

Passos:

1. Instale rimraf para compatibilidade cross-platform na remoção de diretórios: npm install rimraf --save-dev.
2. Crie um diretório dist.
3. Adicione os seguintes scripts ao seu package.json:
   • "prebuild": Um script que exibe "Iniciando processo de build..."
   • "clean": rimraf dist
   • "compile:assets": echo 'Compilando assets...' && mkdir -p dist && echo 'Conteúdo compilado!' > dist/bundle.js
   • "build": npm run clean && npm run compile:assets
   • "postbuild": Um script que exibe "Build concluído com sucesso!"
4. Execute npm run build e verifique a saída e o conteúdo do diretório dist.

Tarefa 4: Variáveis de Ambiente e Argumentos

Crie um script que inicia um servidor em uma porta específica, usando uma variável de ambiente e um argumento.

Passos:

1. Instale cross-env para compatibilidade cross-platform com variáveis de ambiente: npm install cross-env --save-dev.
2. Crie um arquivo server.js:

   // server.js
   const http = require('http');
   const port = process.env.PORT || 3000;
   const env = process.env.NODE_ENV || 'development';
    
   const server = http.createServer((req, res) => {
     res.statusCode = 200;
     res.setHeader('Content-Type', 'text/plain');
     res.end(`Olá do servidor Node.js! Ambiente: ${env}, Porta: ${port}\n`);
   });
    
   server.listen(port, () => {
     console.log(`Servidor rodando em http://localhost:${port}/ no ambiente ${env}`);
   });

3. Adicione um script "start:server" ao seu package.json que use cross-env para definir NODE_ENV como production e PORT como o primeiro argumento passado para o script.
   • Exemplo de script: "start:server": "cross-env NODE_ENV=production PORT=$1 node server.js"
4. Execute npm run start:server -- 8080.
5. Verifique no navegador (http://localhost:8080) e na saída do terminal se o servidor iniciou com as configurações corretas.

4. Resumo e Próximos Passos 🔚

Parabéns! Você dominou a arte de criar e executar npm scripts. Eles são uma ferramenta fundamental no ecossistema Node.js, tornando seu desenvolvimento mais eficiente e organizado.

O que aprendemos:

• A estrutura do objeto "scripts" no package.json.
• Como executar scripts usando npm run.
• A conveniência dos scripts padrão (start, test).
• Como usar binários de dependências locais sem instalação global.
• Encadear comandos sequencialmente (&&) e em paralelo (&).
• Utilizar hooks pre e post para automatizar etapas antes e depois de um script.
• Passar argumentos e definir variáveis de ambiente para scripts.

Próximos Passos:

• Explore mais ferramentas: Pesquise por pacotes como concurrently (para execução paralela robusta), cross-env (para variáveis de ambiente cross-platform), e nodemon (para desenvolvimento).
• Documentação Oficial: Consulte a documentação oficial do NPM sobre package.json scripts para aprofundar seus conhecimentos.
• Integre em seus projetos: Comece a usar npm scripts em todos os seus novos projetos para automatizar tarefas como linting, formatação, testes e inicialização do servidor.

Continue praticando e explorando! A automação é a chave para um desenvolvimento mais produtivo. 💪