Tutorial: Criar um aplicativo Node.js e React no Visual Studio

2025-01-26

Com o Visual Studio, você pode criar facilmente um projeto Node.js e usar o IntelliSense e outros recursos internos que oferecem suporte a Node.js. Neste tutorial, você cria um projeto de aplicativo Web Node.js a partir de um modelo do Visual Studio. Em seguida, você cria um aplicativo simples usando o React.

Neste tutorial, você aprenderá a:

Criar um projeto Node.js
Adicionar pacotes npm
Adicionar código React ao seu aplicativo
Transpile JSX
Anexar o depurador

Importante

A partir do Visual Studio 2022, você pode, alternativamente, criar um projeto React usando o tipo de projeto baseado em CLI recomendado. Algumas das informações neste artigo aplicam-se apenas ao tipo de projeto Node.js (.njsproj). O modelo usado neste artigo não está mais disponível a partir do Visual Studio 2022 versão 17.8 Preview 2.

Antes de começar, aqui está um FAQ rápido para apresentá-lo a alguns conceitos-chave:

O que é Node.js?

Node.js é um ambiente de execução JavaScript no lado do servidor que executa código JavaScript.
O que é npm?

O gerenciador de pacotes padrão para Node.js é npm. Um gerenciador de pacotes facilita a publicação e o compartilhamento de Node.js bibliotecas de código-fonte. O gerenciador de pacotes npm simplifica a instalação, atualização e desinstalação da biblioteca.
O que é React?

O React é uma estrutura front-end para criar uma interface do usuário (UI).
O que é JSX?

JSX é uma extensão de sintaxe JavaScript normalmente usada com o React para descrever elementos da interface do usuário. Você deve transpilar o código JSX para JavaScript simples antes que ele possa ser executado em um navegador.
O que é webpack?

O Webpack agrupa arquivos JavaScript para que eles possam ser executados em um navegador e também possam transformar ou empacotar outros recursos e ativos. Webpack pode especificar um compilador, como Babel ou TypeScript, para transpilar código JSX ou TypeScript para JavaScript simples.

Pré-requisitos

Este tutorial requer os seguintes pré-requisitos:

Visual Studio com a carga de trabalho de desenvolvimento Node.js instalada.

Se você ainda não instalou o Visual Studio:
1. Vá para a página de downloads do Visual Studio para instalar o Visual Studio de graça.
2. No instalador do Visual Studio, selecione o Node.js desenvolvimento carga de trabalho e selecione Instalar.
Se você tiver o Visual Studio instalado, mas precisar da carga de trabalho Node.js:
1. No Visual Studio, vá para Ferramentas >Obter Ferramentas e Recursos.
2. No instalador do Visual Studio, escolha o Node.js desenvolvimento carga de trabalho e selecione Modificar para baixar e instalar a carga de trabalho.
O runtime Node.js instalado:

Se não tiveres o tempo de execução do Node.js instalado, instala a versão LTS, a partir do site Node.js. A versão LTS tem a melhor compatibilidade com outros frameworks e bibliotecas.

As ferramentas de Node.js no Visual Studio Node.js carga de trabalho suportam Node.js versões de arquitetura de 32 bits e 64 bits. O Visual Studio requer apenas uma versão e o instalador do Node.js suporta apenas uma versão de cada vez.

O Visual Studio geralmente deteta o tempo de execução do Node.js instalado automaticamente. Caso contrário, você pode configurar seu projeto para fazer referência ao tempo de execução instalado:
1. Depois de criar um projeto, clique com o botão direito do mouse no nó do projeto e selecione Propriedades.
2. No painel Propriedades do, defina o caminho Node.exe para fazer referência a uma instalação global ou local do Node.js. Você pode especificar o caminho para um intérprete local em cada um dos seus Node.js projetos.

Este tutorial foi testado com Node.js 12.6.2.

Criar um projeto

Primeiro, crie um projeto de aplicativo Web Node.js.

Abra o Visual Studio.
Crie um novo projeto.

Pressione Esc para fechar a janela inicial. Digite Ctrl + Q para abrir a caixa de pesquisa, digite Node.jse, em seguida, escolha Aplicação Web Node.js em Branco - JavaScript. (Embora este tutorial use o compilador TypeScript, as etapas exigem que você comece com o JavaScript modelo.)

Na caixa de diálogo exibida, escolha Criar.

Se não vires o modelo de projeto em Branco Node.js Aplicativo Web, deverás adicionar o trabalho de desenvolvimento Node.js. Para obter instruções detalhadas, consulte o Pré-requisitos.

Visual Studio cria a nova solução e abre seu projeto.

(1) Destacado em negrito está o seu projeto, usando o nome que você deu na caixa de diálogo Novo Projeto. No sistema de arquivos, esse projeto é representado por um arquivo .njsproj na pasta do projeto. Você pode definir propriedades e variáveis de ambiente associadas ao projeto clicando com o botão direito do mouse no projeto e escolhendo Propriedades (ou pressione Alt + Enter). Você pode fazer intercâmbio com outras ferramentas de desenvolvimento, porque o ficheiro de projeto não faz alterações personalizadas na origem do projeto Node.js.

(2) No nível superior está uma solução, que por defeito tem o mesmo nome que o seu projeto. Uma solução, representada por um arquivo .sln no disco, é um contêiner para um ou mais projetos relacionados.

(3) O nó npm mostra todos os pacotes npm instalados. Você pode clicar com o botão direito do mouse no nó npm para procurar e instalar pacotes npm usando uma caixa de diálogo ou instalar e atualizar pacotes usando as configurações em package.json e clicar com o botão direito do mouse nas opções no nó npm.

(4) package.json é um arquivo usado pelo npm para gerenciar dependências de pacotes e versões de pacotes para pacotes instalados localmente. Para obter mais informações, consulte Gerenciar pacotes npm.

(5) Os ficheiros do projeto, tais como server.js, aparecem debaixo do nó do projeto. server.js é o arquivo de inicialização do projeto e é por isso que ele aparece em negrito. Você pode definir o arquivo de inicialização clicando com o botão direito do mouse em um arquivo no projeto e selecionando Definir como Node.js arquivo de inicialização.

Adicionar pacotes npm

Este aplicativo requer os seguintes módulos npm para ser executado corretamente:

reagir
react-dom
expresso
caminho
TS-Carregador
TypeScript
webpack
webpack-cli

Para instalar um pacote:

No Explorador de Soluções , clique com o botão direito no nó npm e selecione Instalar Novos Pacotes npm.
Na caixa de diálogo Instalar Novos Pacotes npm, procure o pacote react e selecione Instalar Pacote.

Na caixa de diálogo Instalar Novos Pacotes npm, você pode optar por instalar a versão mais atual do pacote ou especificar uma versão. Se você optar por instalar as versões atuais, mas encontrar erros inesperados mais tarde, tente instalar as versões exatas do pacote listadas na próxima etapa.

A janela Output no painel inferior do Visual Studio mostra o progresso da instalação do pacote. Abra a janela Output selecionando View>Output ou pressionando Ctrl+Alt+O. No campo Mostrar saída de da janela Saída do, selecione Npm.

Quando instalado, o pacote react aparece sob o nó npm no Gerenciador de Soluções .

O arquivo package.json do projeto é atualizado com as informações do novo pacote, incluindo a versão do pacote.

Em vez de usar a interface do usuário para pesquisar e adicionar o restante dos pacotes, um de cada vez, você pode colar o código do pacote necessário em package.json.

No Gerenciador de Soluções , abra package.json no editor do Visual Studio. Adicione a seguinte seção dependencies antes do final do arquivo:
```
"dependencies": {
  "express": "^4.18.2",
  "path": "^0.12.7",
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "ts-loader": "^9.4.2",
  "typescript": "^5.0.2",
  "webpack": "^5.76.3",
  "webpack-cli": "^5.0.1"
},
```
Se o arquivo já tiver uma seção dependencies, substitua-a pelo código JSON anterior. Para obter mais informações sobre como usar o arquivo package.json, consulte package.json configuration.
Pressione Ctrl+S ou selecione Arquivo>Salvar package.json para salvar as alterações.
No Explorador de Soluções , clique com o botão direito do mouse no nó npm no seu projeto e selecione Instalar Pacotes npm .

Este comando executa o comando npm install diretamente para instalar todos os pacotes listados no packages.json.

Selecione a janela Output no painel inferior para ver o progresso da instalação. A instalação pode levar alguns minutos e você pode não ver os resultados imediatamente. Certifique-se de selecionar Npm no campo mostrar saída de na janela Output.

Após a instalação, os módulos npm aparecem no nó npm no Gerenciador de Soluções .

Observação

Você também pode instalar pacotes npm usando a linha de comando. No Explorador de Soluções , clique com o botão direito do rato no nome do projeto e selecione "Abrir Prompt de Comando Aqui" . Use comandos Node.js padrão para instalar pacotes.

Adicionar arquivos de projeto

Em seguida, adicione quatro novos arquivos ao seu projeto.

app.tsx
webpack-config.js
index.html
tsconfig.json

Para este aplicativo simples, você adiciona os novos arquivos de projeto na raiz do projeto. Para a maioria dos aplicativos, você adiciona os arquivos a subpastas e ajusta as referências de caminho relativas de acordo.

No Gerenciador de Soluções , selecione o nome do projeto e pressione Ctrl+Shift+Aou clique com o botão direito do mouse no nome do projeto e selecione Adicionar>Novo Item.

Se não vir todos os modelos de item, escolha Mostrar Todos os Modelose, em seguida, escolha o modelo de item.
Na caixa de diálogo Adicionar Novo Item, escolha Arquivo JSX TypeScript, digite o nome app.tsxe selecione Adicionar ou OK.
Repita estas etapas para adicionar um arquivo JavaScript chamado webpack-config.js.
Repita estas etapas para adicionar um arquivo HTML chamado index.html.
Repita estas etapas para adicionar um Arquivo de Configuração JSON TypeScript chamado tsconfig.json.

Adicionar código da aplicação

No Gerenciador de Soluções , abra server.js e substitua o código existente pelo seguinte código:
```
'use strict';
var path = require('path');
var express = require('express');

var app = express();

var staticPath = path.join(__dirname, '/');
app.use(express.static(staticPath));

// Allows you to set port in the project properties.
app.set('port', process.env.PORT || 3000);

var server = app.listen(app.get('port'), function() {
    console.log('listening');
});
```
O código anterior usa o Express para iniciar Node.js como seu servidor de aplicativos Web. O código define a porta para o número da porta configurado nas propriedades do projeto, que por padrão é 1337. Se você precisar abrir as propriedades do projeto, clique com o botão direito do mouse no nome do projeto em Gerenciador de Soluções e selecione Propriedades.

Abra o ficheiro app.tsx e adicione o seguinte código:

declare var require: any

var React = require('react');
var ReactDOM = require('react-dom');

export class Hello extends React.Component {
    render() {
        return (
            <h1>Welcome to React!!</h1>
        );
    }
}

ReactDOM.render(<Hello />, document.getElementById('root'));

O código anterior usa sintaxe JSX e React para exibir uma mensagem.

Abra index.html e substitua a seção body pelo seguinte código:
```
<body>
    <div id="root"></div>
    
    <script src="./dist/app-bundle.js"></script>
</body>
```
Esta página HTML carrega app-bundle.js, que contém o código JSX e React transpilado para simples JavaScript. Atualmente, app-bundle.js é um arquivo vazio. Na próxima seção, você configura opções para transpilar o código.

Configurar opções do webpack e do compilador TypeScript

Em seguida, você adiciona o código de configuração do webpack ao webpack-config.js. Você adiciona uma configuração de webpack simples que especifica um arquivo de entrada, app.tsxe um arquivo de saída, app-bundle.js, para agregar e transpilar JSX para JavaScript simples. Para transpilação, você também configura algumas opções do compilador TypeScript. Este código de configuração básica é uma introdução ao webpack e ao compilador TypeScript.

No Gerenciador de Soluções, abra webpack-config.js e adicione o código a seguir.

module.exports = {
    devtool: 'source-map',
    entry: "./app.tsx",
    mode: "development",
    output: {
        filename: "./app-bundle.js"
    },
    resolve: {
        extensions: ['.Webpack.js', '.web.js', '.ts', '.js', '.jsx', '.tsx']
    },
    module: {
        rules: [
            {
                test: /\.tsx$/,
                exclude: /(node_modules|bower_components)/,
                use: {
                    loader: 'ts-loader'
                }
            }
        ]
    }
}

O código de configuração do webpack instrui o webpack a usar o carregador TypeScript para transpilar o JSX.

Abra tsconfig.json e substitua o conteúdo pelo código a seguir, que especifica as opções do compilador TypeScript:

{
  "compilerOptions": {
    "noImplicitAny": false,
    "module": "commonjs",
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5",
    "jsx": "react"
  },
  "exclude": [
    "node_modules"
  ],
  "files": [
    "app.tsx"
  ]
}

O código especifica app.tsx como o arquivo de origem.

Pressione Ctrl+Shift+S ou selecione Ficheiro>Guardar Tudo para salvar todas as alterações.

Transpile o código JSX

No Gerenciador de Soluções , clique com o botão direito do mouse no nome do projeto e selecione Abrir Prompt de Comando Aqui.
No prompt de comando, digite o seguinte comando webpack:

node_modules\.bin\webpack --config webpack-config.js

A janela do prompt de comando mostra o resultado.

Se vires erros em vez da saída anterior, deverás resolvê-los antes que o teu aplicativo funcione. Se as versões do pacote npm forem diferentes das versões especificadas neste tutorial, isso pode causar erros. Para corrigir os erros, tente o seguinte:
- Use as versões exatas mostradas na etapa anterior, se ainda não o fez
  
  Ou, se ainda vê erros:
- Instale as versões mais recentes dos pacotes npm clicando com o botão direito do mouse no nó npm no Gerenciador de Soluções e escolhendo Instalar pacotes npm.
Se uma ou mais versões de pacote forem preteridas e resultarem em um erro, talvez seja necessário instalar uma versão mais recente para corrigir erros. Para obter informações sobre como usar o package.json para controlar versões de pacotes npm, consulte a configuração de package.json.
No Gerenciador de Soluções , clique com o botão direito do mouse no nó do projeto e selecione Adicionar>pasta existente.
Selecione a dist pasta e, em seguida, selecione Selecionar pasta.

O Visual Studio adiciona a pasta dist, que contém app-bundle.js e app-bundle.js.map , ao projeto.
Abra app-bundle.js para ver o código JavaScript transpilado.
Se for perguntado se deseja recarregar arquivos modificados externamente, selecione Sim para Todos.

Sempre que se fizerem alterações em app.tsx, deve-se executar novamente o comando webpack. Para automatizar essa etapa, você pode adicionar um script de construção para transpilar o JSX.

Adicionar um script de construção para transpilar o JSX

As versões do Visual Studio que começam com o Visual Studio 2019 exigem um script de compilação. Em vez de transpilar JSX na linha de comando, como mostrado na seção anterior, você pode transpilar JSX ao criar a partir do Visual Studio.

Abra package.json e adicione a seguinte seção após a seção dependencies:
```
"scripts": {
 "build": "webpack-cli --config webpack-config.js"
}
```
Salve suas alterações.

Executar o aplicativo

Na barra de ferramentas Debug, selecione Web Server (Microsoft Edge) ou Web Server (Google Chrome) como o destino de depuração.

Se souber que o seu destino de depuração preferido está disponível na sua máquina, mas ele não aparecer como uma opção, selecione Navegar com na lista suspensa de destino de depuração. Selecione o destino padrão do navegador na lista e selecione Definir como padrão.
Para executar o aplicativo, pressione F5, selecione o botão de seta verde ou selecione Depurar>Iniciar a Depuração.

Abre-se a janela de consola Node.js que mostra a porta de escuta do depurador.

O Visual Studio inicia o aplicativo iniciando o arquivo de inicialização, server.js.
Feche as janelas do navegador e do console.

Definir um ponto de interrupção e executar o aplicativo

Os pontos de interrupção são o recurso mais básico e essencial da depuração confiável. Um ponto de interrupção indica onde o Visual Studio deve suspender seu código em execução. Em seguida, você pode observar valores de variáveis, comportamento de memória ou se uma ramificação de código está em execução.

Em server.js, clique na margem à esquerda da declaração staticPath para definir um ponto de interrupção:
Para executar o aplicativo, pressione F5 ou selecione Depurar>Iniciar a depuração.

O depurador pausa no ponto de interrupção definido, com a instrução atual realçada. Agora, podes inspecionar o estado da tua aplicação passando o rato sobre as variáveis que estão atualmente no âmbito, usando janelas do depurador, como as janelas Locals e Watch.
Para continuar a executar a aplicação, prima F5, selecione Continuar na barra de ferramentas Depurar ou selecione Depurar>Continuar.

Se pretender utilizar as Ferramentas de Programador do Chrome ou as Ferramentas F12 para Microsoft Edge, prima F12. Você pode usar essas ferramentas para examinar o DOM e interagir com o aplicativo usando o Console JavaScript.
Feche as janelas do navegador e do console.

Definir e atingir um ponto de interrupção no código React do lado do cliente

Na seção anterior, você anexou o depurador ao código Node.js do lado do servidor. Para anexar e atingir pontos de interrupção no código React do lado do cliente, você precisa anexar o depurador ao processo correto. Aqui está uma maneira de iniciar um navegador e anexar um processo para efeitos de depuração.

Ativar o navegador para depuração

Você pode usar o Microsoft Edge ou o Google Chrome. Feche todas as janelas do navegador de destino. Para o Microsoft Edge, também encerre todas as instâncias do Chrome. Como ambos os navegadores compartilham a base de código do Chromium, desligar ambos os navegadores oferece os melhores resultados.

Outras instâncias do navegador podem impedir que o navegador abra com a depuração ativada. As extensões do navegador podem impedir o modo de depuração completa. Poderá ter de utilizar o Gestor de Tarefas para localizar e terminar todas as instâncias do Chrome em execução.

Para iniciar o navegador com a depuração ativada:

Selecione Procurar com na lista suspensa na barra de ferramentas Depurar.
No ecrã Procurar com, com o seu navegador preferido realçado, selecione Adicionar.
Insira o --remote-debugging-port=9222 sinalizador no campo de Argumentos .
Dê ao navegador um novo nome amigável, como Edge com a depuração, ou Chrome com a depuraçãoe, em seguida, selecione OK.
No ecrã Procurar com, selecione Procurar.

Como alternativa, você pode abrir o comando Executar clicando com o botão direito do mouse no botão Iniciar do Windows e digitando:

msedge --remote-debugging-port=9222

ou

chrome.exe --remote-debugging-port=9222

O navegador começa com a depuração ativada. O aplicativo ainda não está em execução, então a página do navegador está vazia.

Anexar o depurador ao script do lado do cliente

No editor do Visual Studio, defina um ponto de interrupção no código-fonte app-bundle.js ou app.tsx.
- Para app-bundle.js, defina o ponto de interrupção na função render(). Para encontrar a função render() no ficheiro app-bundle.js, pressione Ctrl+F ou selecione Editar>Localizar e substituir>Busca Rápida, e digite render no campo de pesquisa.
- Para app.tsx, defina o ponto de interrupção dentro da função render(), na instrução return.
  
  Se você definir o ponto de interrupção em app.tsx, atualize também webpack-config.js para substituir o código a seguir e salve as alterações.
  
  Substitua este código:
```
output: {
    filename: "./app-bundle.js",
},
```
  Com este código:
```
output: {
    filename: "./app-bundle.js",
    devtoolModuleFilenameTemplate: '[resource-path]'  // removes the webpack:/// prefix
},
```
  Essa configuração somente de desenvolvimento permite a depuração no Visual Studio. Por padrão, as referências do webpack no arquivo de mapa de origem incluem o prefixo webpack:///, que impede que o Visual Studio localize o arquivo de origem app.tsx. Essa configuração substitui as referências geradas no arquivo de mapa de origem, app-bundle.js.map, ao criar o aplicativo. Especificamente, essa configuração altera a referência ao arquivo de origem de webpack:///./app.tsx para ./app.tsx, que permite a depuração.
Selecione seu navegador de destino como o destino de depuração no Visual Studio e pressione Ctrl+F5ou selecione Depurar>Iniciar sem Depuração, para executar o aplicativo no navegador.

Se você criou uma configuração de navegador habilitada para depuração com um nome amigável, escolha esse navegador como seu destino de depuração.

O aplicativo é aberto em uma nova guia do navegador.
Selecione Depurar>Anexar ao processoou pressione Ctrl+Alt+P.

Dica

Depois de anexar ao processo pela primeira vez, você pode reanexar rapidamente ao mesmo processo selecionando Depurar>Reanexar ao Processo ou pressionando Shift+Alt+P.
Na caixa de diálogo Anexar ao Processo, obtenha uma lista filtrada de instâncias do navegador às quais pode anexar-se.

Verifique se o depurador correto para o navegador de destino, JavaScript (Chrome) ou JavaScript (Microsoft Edge - Chromium), aparece no campo Anexar a. Digite chrome ou Edge no campo de filtro para filtrar os resultados.
Selecione o processo do navegador com a porta de host correta, localhost neste exemplo. O número da porta 1337 ou localhost também pode aparecer no campo Título para ajudá-lo a selecionar o processo correto.
Selecione Anexar.

O exemplo a seguir mostra uma janela Anexar ao Processo do navegador Microsoft Edge.

Dica

Se o depurador não anexar e você vir a mensagem Não é possível anexar ao processo. Uma operação não é legal no estado atual., use o Gerenciador de Tarefas para fechar todas as instâncias do navegador de destino antes de iniciar o navegador no modo de depuração. As extensões do navegador podem estar em execução e impedindo o modo de depuração completa.
Como o código com o ponto de interrupção já foi executado, atualize a página do navegador para atingir o ponto de interrupção.

Dependendo do seu ambiente, do estado do navegador e das etapas que você seguiu anteriormente, você pode atingir o ponto de interrupção no app-bundle.js ou seu local mapeado em app.tsx. De qualquer forma, você pode percorrer o código e examinar variáveis.

Enquanto o depurador está pausado, você pode examinar o estado do aplicativo passando o mouse sobre as variáveis e usando as janelas do depurador. Para percorrer o código, pressione F11 ou selecione Depurar>Entrar emou pressione F10 ou selecione Depurar>Passar. Para continuar a executar o código, prima F5 ou selecione Continuar. Para obter mais informações sobre recursos básicos de depuração, consulte uma introdução ao depurador.
- Se não for possível entrar no código em app.tsx, tente novamente usar Anexar ao Processo para anexar o depurador, conforme descrito nas etapas anteriores. Certifique-se de que seu ambiente está configurado corretamente:
  - Feche todas as instâncias do navegador, incluindo extensões do Chrome, utilizando o Gestor de Tarefas. Certifique-se de iniciar o navegador no modo de depuração.
  - Verifique se o arquivo de mapa de origem inclui uma referência a ./app.tsx e não webpack:///./app.tsx, o que impede que o depurador do Visual Studio localize app.tsx.
  Ou, tente usar a instrução debugger; em app.tsx, ou então defina pontos de interrupção nas Ferramentas de Programador do Chrome ou nas Ferramentas F12 para o Microsoft Edge.
- Se não conseguires aceder ao código no app-bundle.js, remove o arquivo do mapa de origem app-bundle.js.map.

Próximos passos

Implantar o aplicativo no do Serviço de Aplicativo Linux

Partilhar via