Usando Módulos no Node.js com aplicativos do Microsoft AzureUsing Node.js Modules with Azure applications

Este documento fornece orientação sobre como usar módulos no Node.js com aplicativos hospedados no Microsoft Azure.This document provides guidance on using Node.js modules with applications hosted on Azure. Ele fornece orientações sobre como garantir que seu aplicativo use uma versão específica de um módulo, além de usar módulos nativos com o Azure.It provides guidance on ensuring that your application uses a specific version of a module as well as using native modules with Azure.

Se já estiver acostumado a usar os módulos no Node.js e os arquivos package.json e npm-shrinkwrap.json, as informações a seguir apresentam um rápido resumo do que será discutido neste artigo:If you are already familiar with using Node.js modules, package.json and npm-shrinkwrap.json files, the following information provides a quick summary of what is discussed in this article:

  • O Serviço de Aplicativo do Azure compreende arquivos package.json e npm-shrinkwrap.json e podem instalar módulos com base em entradas nestes arquivos.Azure App Service understands package.json and npm-shrinkwrap.json files and can install modules based on entries in these files.

  • O Azure Cloud Services espera que todos os módulos sejam instalados no ambiente de desenvolvimento, e o diretório node_ modules a ser incluído como parte do pacote de implantação.Azure Cloud Services expects all modules to be installed on the development environment, and the node_modules directory to be included as part of the deployment package. É possível habilitar o suporte para instalar módulos usando arquivos package.json ou npm-shrinkwrap.json nos Serviços de Nuvem; no entanto, essa configuração requer uma personalização dos scripts padrão usados por projetos do Serviço de Nuvem.It is possible to enable support for installing modules using package.json or npm-shrinkwrap.json files on Cloud Services; however, this configuration requires customization of the default scripts used by Cloud Service projects. Para um exemplo de como configurar esse ambiente, consulte Tarefa de Inicialização do Azure para executar npm install e evitar a implantação de módulos de nóFor an example of how to configure this environment, see Azure Startup task to run npm install to avoid deploying node modules

Observação

As Máquinas Virtuais do Azure não são discutidas neste artigo, já que a experiência de implantação em uma VM depende do sistema operacional hospedado pela Máquina Virtual.Azure Virtual Machines are not discussed in this article, as the deployment experience in a VM is dependent on the operating system hosted by the Virtual Machine.

Módulos no Node.jsNode.js Modules

Os módulos são pacotes carregáveis do JavaScript que fornecem funcionalidade específica para seu aplicativo.Modules are loadable JavaScript packages that provide specific functionality for your application. Em geral, instalam-se módulos com a ferramenta de linha de comando npm. Porém, alguns módulos (como http) são fornecidos como parte do pacote central do Node.js.Modules are usually installed using the npm command-line tool, however some modules (such as the http module) are provided as part of the core Node.js package.

Quando os módulos são instalados, são armazenados no diretório node_modules, na raiz da estrutura do diretório de seu aplicativo.When modules are installed, they are stored in the node_modules directory at the root of your application directory structure. Cada módulo dentro do diretório node_módulos mantém seu próprio diretório que contém todos os módulos dos quais ele depende, e esse comportamento se repete para cada módulo até a cadeia de dependência.Each module within the node_modules directory maintains its own directory that contains any modules that it depends on, and this behavior repeats for every module all the way down the dependency chain. Esse ambiente permite que cada módulo instalado tenha seus próprios requisitos de versão para os módulos dos quais depende, porém, o resultado pode ser uma estrutura de diretório muito grande.This environment allows each module installed to have its own version requirements for the modules it depends on, however it can result in quite a large directory structure.

Implantar o diretório node_modules como parte de seu aplicativo aumenta o tamanho da implantação em comparação ao uso de um arquivo package.json ou npm-shrinkwrap.json, mas assegura que a versão dos módulos usados na produção seja igual à dos módulos usados no desenvolvimento.Deploying the node_modules directory as part of your application increases the size of the deployment when compared to using a package.json or npm-shrinkwrap.json file; however, it does guarantee that the versions of the modules used in production are the same as the modules used in development.

Módulos NativosNative Modules

Enquanto a maioria dos módulos são simples arquivos de texto JavaScript, outros são imagens binárias específicas de plataforma.While most modules are simply plain-text JavaScript files, some modules are platform-specific binary images. Estes módulos são compilados no momento da instalação, geralmente usando o Python e o node-gyp.These modules are compiled at install time, usually by using Python and node-gyp. Uma vez que os Serviços de Nuvem do Microsoft Azure contam com a pasta node_modules sendo implantada como parte do aplicativo, qualquer módulo nativo incluído como parte dos módulos instalados deve funcionar em um serviço de nuvem, desde que tenha sido instalado e compilado em um sistema de desenvolvimento do Windows.Since Azure Cloud Services rely on the node_modules folder being deployed as part of the application, any native module included as part of the installed modules should work in a cloud service as long as it was installed and compiled on a Windows development system.

O Serviço de Aplicativo do Azure não dá suporte a todos os módulos nativos e pode falhar ao compilar módulos com pré-requisitos específicos.Azure App Service does not support all native modules, and might fail when compiling modules with specific prerequisites. Embora alguns módulos populares como o MongoDB tenham dependências nativas opcionais e funcionem bem sem elas, duas soluções alternativas foram comprovadamente bem-sucedidas com quase todos os módulos nativos disponíveis hoje:While some popular modules like MongoDB have optional native dependencies and work fine without them, two workarounds proved successful with almost all native modules available today:

  • Execute a npm install em uma máquina do Windows que tenha todos os pré-requisitos do módulo nativo.Run npm install on a Windows machine that has all the native module's prerequisites installed. Em seguida, implante a pasta node_modules criada como parte do aplicativo no Serviço de Aplicativo do Azure.Then, deploy the created node_modules folder as part of the application to Azure App Service.

    • Antes de compilar, verifique se sua instalação local do Node.js tem arquitetura correspondente e se a versão é a mais próxima possível da usada no Azure (os valores atuais podem ser verificados no runtime das propriedades process.arch e process.version).Before compiling, check that your local Node.js installation has matching architecture and the version is as close as possible to the one used in Azure (the current values can be checked on runtime from properties process.arch and process.version).
  • O Serviço de Aplicativo do Azure podem ser configurados para executar scripts bash ou de shell personalizados durante a implantação, oferecendo a você a oportunidade de executar comandos personalizados e configurar com precisão a maneira como o npm install é executado.Azure App Service can be configured to execute custom bash or shell scripts during deployment, giving you the opportunity to execute custom commands and precisely configure the way npm install is being run. Para obter um vídeo mostrando como configurar esse ambiente, consulte Scripts de implantação de site personalizado com Kudu.For a video showing how to configure that environment, see Custom Website Deployment Scripts with Kudu.

Usando um arquivo package.jsonUsing a package.json file

O arquivo package.json é uma maneira de especificar as dependências de nível superior que seu aplicativo requer para que a plataforma de hospedagem possa instalar as dependências, em vez de exigir a inclusão da pasta node_modules como parte da implantação.The package.json file is a way to specify the top level dependencies your application requires so that the hosting platform can install the dependencies, rather than requiring you to include the node_modules folder as part of the deployment. Após o aplicativo ser implantado, o comando instalar npm é usado para analisar o arquivo package.json e instalar todas as dependências listadas.After the application has been deployed, the npm install command is used to parse the package.json file and install all the dependencies listed.

Ao instalar módulos durante o desenvolvimento, você pode usar os parâmetros --save, --save-dev ou --save-optional para adicionar, automaticamente, uma entrada para o módulo de seu arquivo package.json.During development, you can use the --save, --save-dev, or --save-optional parameters when installing modules to add an entry for the module to your package.json file automatically. Para obter mais informações, consulte instalar-npm.For more information, see npm-install.

Um problema potencial com o arquivo package.json é que este só especifica a versão para dependências de nível superior.One potential problem with the package.json file is that it only specifies the version for top-level dependencies. Cada módulo instalado pode ou não especificar a versão dos módulos da qual depende e, desta forma, é possível que você acabe com uma cadeia de dependências diferente daquele usada no desenvolvimento.Each module installed may or may not specify the version of the modules it depends on, and so it is possible that you may end up with a different dependency chain than the one used in development.

Observação

Quando estiver implantando no Serviço de Aplicativo do Azure, se o seu arquivo package.json fizer referência a um módulo nativo, você poderá ver um erro semelhante ao exemplo a seguir ao publicar o aplicativo usando Git:When deploying to Azure App Service, if your package.json file references a native module you might see an error similar to the following example when publishing the application using Git:

npm ERR!npm ERR! Instalar module-name@0.6.0: 'node-gyp configure build'module-name@0.6.0 install: 'node-gyp configure build'

npm ERR!npm ERR! 'cmd "/c" "node-gyp rebuild"' falhou com 1'cmd "/c" "node-gyp configure build"' failed with 1

Usando um arquivo npm-shrinkwrap.jsonUsing a npm-shrinkwrap.json file

O arquivo npm-shrinkwrap.json é uma tentativa de resolver as limitações da versão do módulo do arquivo package.json.The npm-shrinkwrap.json file is an attempt to address the module versioning limitations of the package.json file. Enquanto o arquivo package.json inclui apenas versões para os módulos de nível superior, o arquivo npm-shrinkwrap.json contém os requisitos de versão para a cadeia de dependências de módulo completo.While the package.json file only includes versions for the top-level modules, the npm-shrinkwrap.json file contains the version requirements for the full module dependency chain.

Quando seu aplicativo estiver pronto para produção, você poderá bloquear os requisitos de versão e criar um arquivo npm-shrinkwrap.json usando o comando npm shrinkwrap.When your application is ready for production, you can lock down version requirements and create an npm-shrinkwrap.json file by using the npm shrinkwrap command. Esse comando usará as versões atualmente instaladas na pasta node_modules e registrará essas versões no arquivo npm-shrinkwrap.json.This command will use the versions currently installed in the node_modules folder, and record these versions to the npm-shrinkwrap.json file. Após o aplicativo ser implantado no ambiente de hospedagem, o comando instalar npm é usado para analisar o arquivo npm-shrinkwrap.json e instalar todas as dependências listadas.After the application has been deployed to the hosting environment, the npm install command is used to parse the npm-shrinkwrap.json file and install all the dependencies listed. Para obter mais informações, consulte npm-shrinkwrap.For more information, see npm-shrinkwrap.

Observação

Quando estiver implantando no Serviço de Aplicativo do Azure, se o seu arquivo npm-shrinkwrap.json fizer referência a um módulo nativo, você poderá ver um erro semelhante ao exemplo a seguir ao publicar o aplicativo usando Git:When deploying to Azure App Service, if your npm-shrinkwrap.json file references a native module you might see an error similar to the following example when publishing the application using Git:

npm ERR!npm ERR! Instalar module-name@0.6.0: 'node-gyp configure build'module-name@0.6.0 install: 'node-gyp configure build'

npm ERR!npm ERR! 'cmd "/c" "node-gyp rebuild"' falhou com 1'cmd "/c" "node-gyp configure build"' failed with 1

Próximas etapasNext steps

Agora que você aprendeu como usar os módulos no Node.js com o Azure, aprenda como especificar a versão do Node.js, compilar e implantar um aplicativo Web Node.js e Como usar a Interface de Linha de Comando do Azure para Mac e Linux.Now that you understand how to use Node.js modules with Azure, learn how to specify the Node.js version, build and deploy a Node.js web app, and How to use the Azure Command-Line Interface for Mac and Linux.

Para saber mais, confira o Centro de desenvolvedores do Node.js.For more information, see the Node.js Developer Center.