Tutoriais

Aplicação web

Neste tutorial você aprenderá os comandos básicos para criar uma aplicação web na plataforma da Azion usando o comando edge_applications e os seus três subcomandos:

init, para definir um nome e um template para a sua aplicação web.
build, para construir a aplicação com base no template escolhido no subcomando init.
publish, para publicar a aplicação na plataforma da Azion.

Nota: o processo passo a passo para criar uma aplicação web será apresentado no tutorial Construindo passo a passo uma aplicação web usando a Azion CLI. Porém, antes disso é importante que você conheça o conceito e os detalhes técnicos de cada etapa individualmente. Leia os tópicos seguintes antes de praticar a criação de aplicações web com a CLI.

Inicialização

O processo de inicialização cria o ambiente necessário para a construção da sua aplicação web. Para isso, é necessário que você previamente:

Defina o nome da sua aplicação web.
Escolha um dos três templates disponíveis na CLI.
Inicialize um projeto JavaScript com o Node.js® ¹⁰ runtime environment.

A CLI atualmente disponibiliza três templates para a construção de aplicações web:

JavaScript,
Flareact, ou
Next.js.

Visite os sites dos frameworks Flareact e Next.js para maiores informações.

Nota: os nomes dos templates listados acima são os originais da linguagem JavaScript e dos frameworks Flareact e Next.js. Para inicializar a sua aplicação web, você deve substituí-los no comando init da CLI por javascript, flareact, ou nextjs, respectivamente.

Por enquanto, os comandos apresentados a seguir são apenas informativos. Sugerimos que você apenas entenda os conceitos e práticas apresentadas neste tópico, sem tentar executá-los. Você utilizará todos eles na prática quando criarmos efetivamente uma aplicação web no tópico 2.2. Criando uma aplicação web.

O comando init inicializa uma aplicação web com a seguinte sintaxe:

azioncli edge_applications init --name <"application_name"> --type <template>

Note: as flags --name e --type não são obrigatórias. Caso não sejam informadas, a CLI utilizará o nome definido em seu package.json, e o tipo será autodetectado. Se a flag --name for informada, seu package.json será atualizado.

Caso não exista um arquivo de configuração package.json no diretório do seu aplicativo web, a CLI apresentará a seguinte mensagem de erro:

Error: Failed to find package.json in current directory. Verify if your are currently in your project's directory

Nesse caso, crie um arquivo package.json de configuração do seu projeto no mesmo diretório da sua aplicação web. Em seguida, execute novamente o comando, a fim de inicializar a aplicação.

Dica: a melhor solução para criar um arquivo package.json é inicializar um projeto Node.js no diretório da sua aplicação web. Para isso, utilize o comando abaixo do Node.js runtime environment:

npm init -y

Resposta do comando no terminal:

Wrote to /Users/<user_name>/web-app-proj/package.json:

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

No exemplo acima, o comando foi executado na pasta web-app-proj da aplicação web. Observe que o arquivo package.json criado possui uma chave “name” com o valor “web-app-proj”, que é o nome da pasta criada para armazenar a aplicação web. Além disso, a chave “main” estabelece que o arquivo de execução do projeto é o arquivo index.js.

Caso você opte por criar o arquivo package.json manualmente, lembre-se de criar as respectivas chaves e valores que atendam especificamente ao seu projeto.

Nota: a flag -y é opcional. Caso queira responder às perguntas do instalador de pacotes npm durante o processo de criação do projeto, não inclua essa chave. Por exemplo, você poderia modificar a chave “name” para um valor diferente da pasta atual do projeto. Caso seja mantida a flag -y, todos os valores do arquivo package.json serão configurados automaticamente.

Após a criação do projeto Node.js, digite o comando ls para confirmar a criação do arquivo package.json.

Construção

A segunda etapa na criação de uma aplicação web é a sua construção com base nos atributos informados no comando init. O comando utilizado para construir a aplicação é o comando build, que possui a seguinte sintaxe:

azioncli edge_applications build

O comando build não necessita de nenhuma informação adicional para construir a sua aplicação web. A flag --help é única disponível no comando, que apresenta uma pequena tela de ajuda:

azioncli edge_applications build --help

Build your Web application

USAGE
azioncli edge_applications build [flags]

EXAMPLES
$ azioncli build

FLAGS
-h, --help   help for build

LEARN MORE
Use 'azioncli <command> <subcommand> --help' for more information about a command

Um requisito para a utilização do comando build é a presença do framework webPack® ¹¹ instalado no seu computador.

Caso contrário, a seguinte mensagem de erro será apresentada pela CLI:

Running build step command:

$ npx --package=webpack@5.72.0 --package=webpack-cli@4.9.2 -- webpack --config ./azion/webpack.config.js -o ./worker --mode production

...

Error: Failed to run build step command. Verify if the command is correct and/or check its output for more details

Nesse caso, lembre-se de inicializar um projeto JavaScript no diretório da sua aplicação web com o comando npm init -y, que automaticamente criará os arquivos do framework webPack, além de outros arquivos padrão. Depois, basta executar novamente o comando azioncli edge_applications build.

Publicação

A etapa final para a criação de uma aplicação web é a sua publicação na plataforma da Azion. O comando publish realiza essa tarefa de forma automática com a seguinte sintaxe:

azioncli edge_applications publish

Dica: o comando publish executa internamente e de forma transparente para o desenvolvedor, um comando build. Dessa forma, é possível criar uma aplicação Web com a CLI apenas configurando-a com os comandos init e publicando-a em seguida com o comando publish. Entretanto, recomendamos utilizar o comando build durante a fase de desenvolvimento da sua aplicação, a fim de ajustar as configurações antes de publicá-la na plataforma da Azion.

Agora que você acompanhou os detalhes de configuração para a sua aplicação web, poderá seguir os passos do tópico seguinte para efetivamente criá-la. Com os conceitos apresentados até aqui, você seguirá o processo de forma direta e segura.

Construindo passo a passo uma aplicação web usando a Azion CLI

Neste tutorial serão abordados todos os passos necessários para a criação de um aplicação web usando os comandos da Azion CLI.

Requisitos: Antes de iniciar a construção da sua aplicação web, você precisa:

Criar uma pasta no sistema de arquivos do seu computador, na qual será armazenada a aplicação web; ela pode estar localizada em qualquer lugar de sua preferência.
Baixar e instalar o Node.js JavaScript runtime compatível com o seu sistema operacional a partir do site oficial; essa instalação inclui o gerenciador de pacotes npm.
Baixar e instalar a Azion CLI, versão 0.46.0 ou superior, conforme apresentado no tópico Instalação.
Criar um personal token no RTM e configurá-lo na CLI. Veja o tópico Autorização na Plataforma da Azion.

Para criar uma aplicação web usando a CLI, siga estes passos:

Crie uma pasta no sistema de arquivos do seu computador com o nome da sua aplicação; por exemplo, my-web-app.

Nota: a pasta da sua aplicação pode estar em qualquer local de sua preferência.

Dica: você poderá criar uma pasta no seu sistema de arquivos usando diretamente o terminal. Para isso digite o comando mkdir my-web-app.
Abra o terminal no seu computador e navegue até a pasta da aplicação web com o comando cd /<path>/my-web-app, por exemplo.

Dica: você poderá abrir o terminal diretamente na pasta da sua aplicação web de forma simples e prática. Para isso, abra o gerenciador de arquivos do sistema operacional do seu computador, localize a pasta da sua aplicação web, neste caso, my-web-app, e arraste-a para cima do ícone do aplicativo terminal do seu computador. Essa dica funciona na maioria dos sistemas operacionais.
Execute o comando abaixo para verificar se a Azion CLI está corretamente instalada:

azioncli --version

Resposta da CLI, que poderá ser diferente dependendo da versão da Azion CLI instalada no seu computador:
```
     azioncli version 0.46.0
```
Nota: a versão da azioncli deve ser 0.46.0, ou superior. Se necessário, siga os passos para reinstalar a CLI no tópico Instalação.
Inicialize um projeto Node.js na pasta da aplicação com o comando:

npm init -y

O comando cria um arquivo denominado package.json no mesmo diretório da aplicação web, que será o arquivo de configuração do projeto.

Resposta da CLI:
```
 Wrote to /Users/<user_name>/<project_folder>/package.json:

 {
 "name": "my-web-app",
 "version": "1.0.0",
 "description": "",
 "main": "index.js",
 "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
 },
 "keywords": [],
 "author": "",
 "license": "ISC"
 }
```
Nota: na linha Wrote to /Users/… da mensagem acima, <user_name> é o seu nome de usuário no sistema operacional do computador, e <project_folder> é a pasta escolhida por você para arquivar o projeto da web application. Em vez de criar um novo projeto Node.js na pasta da sua aplicação web, você poderá utilizar um projeto já existente.
Crie um arquivo denominado index.js na mesma pasta do projeto com o seguinte comando:
```
 echo "async function handleRequest(request) {
     return new Response('Congratulations! This is your web application on Azion!',{status:200})
 }
 addEventListener('fetch', event => {
     event.respondWith(handleRequest(event.request))
 })" > index.js
```
Nota: copie todas as linhas do comando acima, desde a palavra echo até index.js, e cole no terminal. Em seguida, simplesmente pressione ENTER ou RETURN para executar o comando, sem alterá-lo. O arquivo index.js será criado com o código JavaScript do exemplo.

Caso desejável, você poderá substituir o código do arquivo index.js por outro de sua preferência.

Aviso: lembre-se apenas de salvar o arquivo index.js no formato plain text, sem qualquer formatação de estilos ou caracteres especiais. Utilize para isso um editor de textos puro de sua preferência. Caso contrário, caracteres especiais e ocultos poderão ser incluídos no arquivo sem que você perceba, comprometendo futuramente o funcionamento da função contida no arquivo. Basicamente, evite editores de texto que permitem incluir qualquer recurso extra além de texto, como estilos, imagens, e tabelas, por exemplo.
Execute o comando:

azioncli edge_applications init --name "my-app" --type javascript

O comando acima cria uma pasta denominada azion no mesmo diretório da aplicação web com três arquivos e apresenta uma resposta semelhante a essa:
```
 Auto-detected Project Settings (Javascript)
 Template successfully fetched and configured

 Your project my-app was initialized successfully
     [ General Instructions ]
     [ Usage ]
         - Build Command: npm run build
         - Publish Command: npm run deploy
     [ Notes ]
         - Node 16x or higher%   
```
Dica: para examinar o conteúdo da pasta azion criada pelo comando edge_applications init, digite o comando ls azion/, sem sair do diretório atual da aplicação. Serão apresentados os seguintes arquivos:
```
     README.md		azion.json		config.json		webdev.env		webpack.config.js
```
Execute o comando:

azioncli edge_applications build

A CLI responde com a seguinte mensagem no monitor:
```
 Building your Web Application
 Your Web Application was built successfully
```
Nota: pode ser que o comando azioncli edge_applications build retorne a seguinte mensagem de erro:
```
 zsh: permission denied: azion  
```
Nesse caso, ou o Personal Token é inexistente ou ele está expirado. Você deve então configurar um novo token para autorizar o comando azioncli edge_applications build na plataforma da Azion. Para isso, crie um Personal Token pessoal no RTM e execute em seguida o comando, substituindo o campo <my_personal_token> pelo novo token:

azioncli configure --token <my_personal_token>

Um token é uma sequência aleatória de caracteres com o formato azionxxxxxxxxxxx.

Resposta da CLI:
```
 Token saved in /Users/<user_name>/.azion/credentials
```
Nota: <user_name> é o diretório padrão do usuário no sistema de arquivos do computador.

Veja os procedimentos para a criação e o gerenciamento de token pessoais na documentação de referência.

Execute o comando:

azioncli edge_applications publish

A resposta da CLI será semelhante ao exemplo abaixo:

 Building your Web Application

 Your Web Application was built successfully
 Created Edge Function my-app with ID 1909
 Created Edge Application my-app with ID 123456789
 Created Domain my-app with ID 123456789
 Your Web Application was published successfully

 To visualize your application access the domain: xxxxxxx.map.azionedge.net

 Content is being propagated to all Azion POPs and it might take a few minutes for all edges to be up to date

Copie a URL que aparece no final da mensagem do passo 11, representada neste exemplo pela string xxxxxxxxxx.map.azionedge.net; os caracteres “x” são alfanuméricos e aleatórios.
Cole a URL na barra de endereço do seu navegador web.
Pressione a tecla ENTER ou RETURN; você verá a seguinte mensagem na tela do seu navegador:
```
Congratulations! This is your web application on Azion!
```

Nota: a publicação de uma aplicação web pelo RTM ou pela CLI não é um processo instantâneo. Existe um tempo de propagação e configuração da aplicação nas edge locations da Azion. Pode ser necessário aguardar alguns minutos para a ativação da URL e a efetiva visualização da página da aplicação no navegador.

Note que, além de ter criado automaticamente uma URL para a sua aplicação, a CLI apresenta outras informações ao final do subcomando publish, como pode ser observado na resposta do passo 11. As mais importantes são:

Created Edge Function with ID 7026 - a CLI criou uma nova Edge Function com o ID 7026.
Created Edge Application with ID 1663959737 - a CLI criou uma nova Edge Application com o ID 1663959737.
Updated Rules Engine with ID 130309 - a CLI atualizou a Rule Engine com ID 130309.
Created Domain with ID 1663956565 - o domain criado, cuja URL aparece no final da mensagem do passo 11, e que pode ser utilizada para abrir a sua aplicação web no navegador.

Navegue pelo RTM para visualizar os novos elementos que os comandos da CLI criaram neste tutorial:

Products Menu > Domains, to show the new Web application domain.
Products Menu > Edge Application, to show the new my-app application.
Products Menu > Edge Functions, to show the new my-app function.

Dica: caso deseje recuperar a URL da sua aplicação, acesse o menu Products > Domains. Você verá uma lista dos seus domínios, inclusive aqueles criados pelos comandos da CLI.

Neste tutorial você criou uma aplicação web completa somente utilizando comandos da Azion CLI.

Para consultar a lista completa dos comandos, subcomandos, e flags da Azion CLI, visite o guia de referência da CLI.

Não encontrou o que procurava? Abra um ticket.