Como criar um módulo Node.js

O autor selecionou a Open Internet/Free Speech Fund para receber uma doação como parte do programa Write for DOnations.

Introdução

No Node.js, um module é uma coleção de funções e objetos do JavaScript que podem ser utilizados por aplicativos externos. Descrever um trecho de código como um módulo se refere menos ao que o código é do que aquilo que ele faz — qualquer arquivo Node.js pode ser considerado um módulo caso suas funções e dados sejam feitos para programas externos.

Como os módulos fornecem unidades de funcionalidade que podem ser reutilizadas em muitos programas maiores, eles permitem a criação de aplicativos acoplados que escalam com a complexidade e abre portas para que você compartilhe seu código com outros desenvolvedores. Conseguir escrever módulos que exportam funções e dados úteis permitirá que você contribua para a comunidade do Node.js — de fato, todos os pacotes que você utiliza no npm foram agrupados e compartilhados como módulos. Isso torna a criação de módulos uma habilidade essencial para um desenvolvedor do Node.js.

Neste tutorial, você criará um módulo Node.js, que sugere quais cores os desenvolvedores Web devem usar em seus projetos. Você desenvolverá o módulo, armazenando as cores como uma matriz e fornecendo uma função para receber uma cor aleatoriamente. Depois de fazer isso, você executará várias maneiras de importar um módulo em um aplicativo Node.js.

Pré-requisitos

• Será necessário o Node.js e o npm instalados em seu ambiente de desenvolvimento. Este tutorial usa a versão 10.17.0. Para instalar essa versão em macOS ou Ubuntu 18.04, siga os passos descritos no artigo sobre Como instalar o Node.js e criar um ambiente de desenvolvimento local em macOS ou a seção entitulada Instalando usando um PPA, do artigo sobre Como instalar o Node.js no Ubuntu 18.04. Por ter o Node.js instalado, você também tem o npm instalado; este tutorial usa a versão 6.11.3.
• Você também deve estar familiarizado com o arquivo package.json, e ter experiência com os comandos npm também será útil. Para obter esta experiência, siga Como utilizar os módulos do Node.js com o npm e o package.json, em particular o Passo 1 — Criando um arquivo package.json.
• Ele também ajudará você a se sentir mais à vontade com o REPL (leitura-avaliação-impressão-loop) do Node.js. Você usará isso para testar seu módulo. Caso precise de mais informações sobre isso, leia nosso guia sobre Como usar o REPL do Node.js.

Passo 1 — Criando um módulo

Este passo guiará você na criação de seu primeiro módulo Node.js. Seu módulo terá uma coleção de cores em uma matriz e dará uma função para retornar uma cor aleatoriamente. Você usará a propriedade exports integrada do Node.js para fazer a função e a matriz disponíveis para programas externos.

Primeiro, comece decidindo quais dados a respeito das cores você armazenará em seu módulo. Todas as cores serão um objeto que contém uma propriedade de name que as pessoas poderão identificar facilmente e uma propriedade de code, que é uma string que contém um código de cor em HTML. Os códigos de cor do HTML são números hexadecimais de seis dígitos, que permitem que você altere a cores de elementos em uma página Web. Você pode aprender mais a respeito dos códigos de cores do HTML lendo este artigo sobre Códigos de cores e nomes em HTML.

Então, você decidirá quais cores deseja em seu módulo. Seu módulo terá uma matriz chamada allColors que terá seis cores. Seu módulo também incluirá uma função chamada getRandomColor(), que selecionará aleatoriamente uma cor de sua matriz e a retornará.

Em seu terminal, crie uma nova pasta chamada de colors e vá até ela:

mkdir colors
cd colors

Inicialize o npm para que outros programas possam importar este módulo mais a frente no tutorial:

npm init -y

Você usou o sinalizador -y para pular as instruções usuais para personalizar seu package.json. Se este fosse um módulo que você quisesse publicar para npm, teria de responder a todas essas instruções com dados relevantes, como explicado em Como utilizar os módulos do Node.js com o npm e o package.json.

Neste caso, seu resultado será:

Output
{
  "name": "colors",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Agora, abra um editor de texto de linha de comando, como o nano, e crie um novo arquivo para servir como o ponto de entrada para o seu módulo:

nano index.js

Seu módulo fará algumas coisas. Primeiro, você definirá uma classe Color. Sua classe Color será instanciada com o nome e código HTML dela. Adicione as seguintes linhas para criar a classe:

class Color {
  constructor(name, code) {
    this.name = name;
    this.code = code;
  }
}

Agora que tem sua estrutura de dados para a Color, adicione algumas instâncias em seu módulo. Escreva a seguinte matriz destacada para seu arquivo:

class Color {
  constructor(name, code) {
    this.name = name;
    this.code = code;
  }
}

const allColors = [
  new Color('brightred', '#E74C3C'),
  new Color('soothingpurple', '#9B59B6'),
  new Color('skyblue', '#5DADE2'),
  new Color('leafygreen', '#48C9B0'),
  new Color('sunkissedyellow', '#F4D03F'),
  new Color('groovygray', '#D7DBDD'),
];

Por fim, digite uma função que seleciona aleatoriamente um item da matriz allColors que você acabou de criar:

class Color {
  constructor(name, code) {
    this.name = name;
    this.code = code;
  }
}

const allColors = [
  new Color('brightred', '#E74C3C'),
  new Color('soothingpurple', '#9B59B6'),
  new Color('skyblue', '#5DADE2'),
  new Color('leafygreen', '#48C9B0'),
  new Color('sunkissedyellow', '#F4D03F'),
  new Color('groovygray', '#D7DBDD'),
];

exports.getRandomColor = () => {
  return allColors[Math.floor(Math.random() * allColors.length)];
}

exports.allColors = allColors;

A palavra-chave exports faz referência a um objeto global, disponível em todo módulo do Node.js. Todas as funções e objetos armazenados em um objeto exports do módulo são expostas quando outros módulos do Node.js o importam. A função getRandomColor() foi criada diretamente no objeto exports, por exemplo. Então, foi adicionada uma propriedade allColors ao objeto exports, que faz referência à matriz constante local allColors, criada mais cedo no script.

Quando outros módulos importam esse módulo, a matriz allColors e a função getRandomColor() serão expostas e ficarão disponíveis para o uso.

Salve e saia do arquivo.

Até agora, você criou um módulo que contém uma matriz de cores e uma função que retorna uma cor aleatoriamente. Você também exportou a matriz e a função, de modo que programas externos possam usá-las. No próximo passo, você utilizará seu módulo em outros aplicativos para demonstrar os efeitos do export.

Passo 2 — Testando seu módulo com o REPL

Antes de desenvolver um aplicativo completo, reserve um momento para confirmar que seu módulo está funcionando. Neste passo, você utilizará o REPL para carregar o módulo colors. Enquanto no REPL, você chamará a função getRandomColor() para conferir se ela se comporta como o esperado.

Inicie o REPL do Node.js na mesma pasta que o arquivo index.js:

node

Quando o REPL iniciar, você verá o prompt >. Isso significa que você pode digitar o código do JavaScript que será avaliado imediatamente. Caso queira ler mais sobre isso, siga nosso guia sobre como usar o REPL.

Primeiro, digite o seguinte:

colors = require('./index');

Neste comando, o require() carrega o módulo colors como seu ponto de entrada. Quando pressionar ENTER, receberá:

Output
{
  getRandomColor: [Function],
  allColors: [
    Color { name: 'brightred', code: '#E74C3C' },
    Color { name: 'soothingpurple', code: '#9B59B6' },
    Color { name: 'skyblue', code: '#5DADE2' },
    Color { name: 'leafygreen', code: '#48C9B0' },
    Color { name: 'sunkissedyellow', code: '#F4D03F' },
    Color { name: 'groovygray', code: '#D7DBDD' }
  ]
}

O REPL nos mostra o valor de colors, que são todas as funções e objetos importados do arquivo index.js. Quando utilizar a palavra-chave require, o Node.js retorna todo o conteúdo dentro do objeto exports de um módulo.

Lembre-se que você adicionou o getRandomColor() e o allColors para o exports no módulo colors. Por este motivo, você os vê no REPL quando eles são importados.

No prompt, teste a função getRandomColor():

colors.getRandomColor();

Você receberá uma cor aleatória:

Output
Color { name: 'groovygray', code: '#D7DBDD' }

Como o índice é aleatório, seu resultado pode variar. Agora que confirmou que o módulo colors está funcionando, saia do REPL do Node.js:

.exit

Isso retornará você para o terminal de linha de comando.

Você acabou de confirmar que seu módulo funciona como o esperado utilizando o REPL. Em seguida, você aplicará esses mesmos conceitos e carregará seu módulo em um aplicativo, como faria em um projeto real.

Passo 3 — Salvando seu módulo local como uma dependência

Enquanto testava seu módulo no REPL, você o importou com um relative path. Isso significa que você utilizou o local do arquivo index.js em relação ao diretório de trabalho para obter o conteúdo. Enquanto isso funciona, geralmente, para uma melhor experiência de programação, é melhor importar os módulo pelos seus nomes, para que a importação não seja corrompida quando o contexto for alterado. Neste passo, você instalará o módulo colors com o recurso install local do módulo do npm.

Configure um novo módulo Node.js fora da pasta colors. Primeiro, vá até o diretório anterior e crie uma nova pasta:

cd ..
mkdir really-large-application

Vá para seu novo projeto:

cd really-large-application

Assim como o módulo colors, inicialize sua pasta com o npm:

npm init -y

O seguinte package.json será gerado:

Output
{
  "name": "really-large-application",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Agora, instale seu módulo colors e utilize o sinalizador --save para que ele seja gravado em seu arquivo package.json:

npm install --save ../colors

Você acabou de instalar o módulo colors no novo projeto. Abra o arquivo package.json para ver a nova dependência local:

nano package.json

Você descobrirá que as seguintes linhas destacadas foram adicionadas:

{
  "name": "really-large-application",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "colors": "file:../colors"
  }
}

Saia do arquivo.

O módulo colors foi copiado para o seu diretório node_modules. Verifique se ele está lá com o seguinte comando:

ls node_modules

Isso dará o seguinte resultado:

Output
colors

Utilize seu módulo local instalado neste novo programa. Abra novamente seu editor de texto para criar outro arquivo JavaScript:

nano index.js

Seu programa importará primeiro o módulo colors. Então, ele escolherá uma cor aleatoriamente, utilizando a função getRandomColor(), fornecida pelo módulo. Por fim, ele imprimirá uma mensagem para o console, que diz ao usuário qual cor usar.

Digite o seguinte código no index.js:

const colors = require('colors');

const chosenColor = colors.getRandomColor();
console.log(`You should use ${chosenColor.name} on your website. It's HTML code is ${chosenColor.code}`);

Salve e saia deste arquivo.

Seu aplicativo agora informará ao usuário uma opção de cor aleatória para um componente do site.

Execute este script com:

node index.js

Seu resultado será parecido com este:

Output
You should use leafygreen on your website. It's HTML code is #48C9B0

Você instalou o módulo colors com êxito e pode gerenciá-lo como qualquer outro pacote npm utilizado em seu projeto. No entanto, caso tenha adicionado mais cores e funções ao seu módulo colors local, será necessário executar o npm update em seus aplicativos para conseguir usar as novas opções. No próximo passo, você utilizará o módulo local colors de outra maneira e receberá atualizações automáticas quando o código do módulo for alterado.

Passo 4 — Vinculando um módulo local

Caso seu módulo local esteja em desenvolvimento intenso, a atualização contínua de pacotes pode ser algo entediante. Uma alternativa seria fazer o link dos módulos. Vincular um módulo garante que quaisquer atualizações sejam imediatamente refletidas nos aplicativos que o usam.

Neste passo, você vinculará o módulo colors ao seu aplicativo. Você também modificará o módulo colors e confirmará que suas alterações mais recentes funcionam no aplicativo sem precisar instalar novamente ou atualizar.

Primeiro, desinstale seu módulo local:

npm un colors

O npm vincula módulos utilizando symbolic links (ou symlinks), que são referências que apontam para arquivos ou diretórios em seu computador. Vincular um módulo é um feito através de dois passos:

1. Criar um global link para o module.npm cria um symlink entre seu diretório global node_modules e o diretório do seu módulo. O diretório global node_modules é o local onde todos os pacotes npm do sistema estão instalados (qualquer pacote que instale com o sinalizador -g).
2. Criar um local link. O npm cria um symlink entre seu projeto local que está utilizando o módulo e o link global do módulo.

Primeiro, crie o link global retornando para a pasta colors e usando o comando link:

cd ../colors
sudo npm link

Assim que terminar, seu o shell irá gerar:

Output
/usr/local/lib/node_modules/colors -> /home/sammy/colors

Você acabou de criar um symlink em sua pasta node_modules para seu diretório colors.

Volte para a pasta really-large-application e vincule o pacote:

cd ../really-large-application
sudo npm link colors

Você receberá um resultado similar ao seguinte:

Output
/home/sammy/really-large-application/node_modules/colors -> /usr/local/lib/node_modules/colors -> /home/sammy/colors

Como o resultado mostra, você acabou de criar um symlink a partir do diretório local node_modules do really-large-application para o symlink colors em seu node_modules global, que aponta para o diretório com o módulo colors.

O processo de vinculação está completo. Execute seu arquivo para garantir que ele ainda funciona:

node index.js

Seu resultado será parecido com este:

Output
You should use sunkissedyellow on your website. It's HTML code is #F4D03F

A funcionalidade do seu programa está intacta. Em seguida, teste se as atualizações foram imediatamente aplicadas. No seu editor de texto, abra novamente o arquivo index.js no módulo colors:

cd ../colors
nano index.js

Agora, adicione uma função que seleciona o melhor tom do azul que existe. Ela não recebe argumentos e sempre retorna o terceiro item da matriz allColors. Adicione essas linhas ao final do arquivo:

class Color {
  constructor(name, code) {
    this.name = name;
    this.code = code;
  }
}

const allColors = [
  new Color('brightred', '#E74C3C'),
  new Color('soothingpurple', '#9B59B6'),
  new Color('skyblue', '#5DADE2'),
  new Color('leafygreen', '#48C9B0'),
  new Color('sunkissedyellow', '#F4D03F'),
  new Color('groovygray', '#D7DBDD'),
];

exports.getRandomColor = () => {
        return allColors[Math.floor(Math.random() * allColors.length)];
        }

exports.allColors = allColors;

exports.getBlue = () => {
  return allColors[2];
}

Salve e saia do arquivo. Abra novamente o arquivo index.js na pasta really-large-application:

cd ../really-large-application
nano index.js

Faça uma chamada para a função recém-criada getBlue() e imprima uma frase com as propriedades da cor. Adicione essas instruções ao final do arquivo:

const colors = require('colors');

const chosenColor = colors.getRandomColor();
console.log(`You should use ${chosenColor.name} on your website. It's HTML code is ${chosenColor.code}`);

const favoriteColor = colors.getBlue();
console.log(`My favorite color is ${favoriteColor.name}/${favoriteColor.code}, btw`);

Salve e saia do arquivo.

O código agora utiliza a função recém-criada getBlue(). Execute o arquivo como antes:

node index.js

Você receberá um resultado como:

Output
You should use brightred on your website. It's HTML code is #E74C3C
My favorite color is skyblue/#5DADE2, btw

Seu script conseguiu utilizar a função mais recente em seu módulo colors, sem precisar executar o npm update. Isso facilitará as alterações neste aplicativo em desenvolvimento.

Enquanto escreve aplicativos maiores e mais complexos, pense como o código relacionado pode ser agrupado em módulos e como quer que esses módulos sejam configurados. Caso seu módulo seja usado apenas por um programa, ele pode ficar dentro do mesmo projeto e ser referenciado por um caminho relativo. Mas caso seu módulo seja mais tarde compartilhado separadamente, ou ele exista em um local muito diferente do projeto que você está trabalhando agora, a ideia de instalar ou vinculá-lo pode ser algo mais viável. Módulos em desenvolvimento ativo também se beneficiam das atualizações automáticas da vinculação. Caso o módulo não esteja em um desenvolvimento ativo, usar o npm install pode ser a opção mais fácil.

Conclusão

Neste tutorial, você aprendeu que um módulo Node.js é um arquivo JavaScript com funções e objetos que podem ser usados por outros programas. Então, você criou um módulo e anexou suas funções e objetos ao objeto global exports para torná-los disponíveis para programas externos. Por fim, você importou aquele módulo em um programa, demonstrando como os módulos se reúnem em aplicativos maiores.

Agora que você sabe como criar módulos, pense no tipo de programa que deseja escrever e como o dividir em vários componentes, mantendo cada conjunto único de atividades e dados em seus próprios módulos. Quanto mais prática você obter ao escrever os módulos, melhor a capacidade de escrever programas Node.js de qualidade em sua jornada de aprendizagem. Para trabalhar com um exemplo de um aplicativo Node.js que utiliza os módulos, consulte nosso tutorial Como configurar um aplicativo Node.js para produção no Ubuntu 18.04.