Tutorials

Web application

In this tutorial you’ll create a web application on the Azion platform using the edge_applications command and its three subcommands:

init, to define a name and template for your web application.
build, to build the application based on the template chosen in the init subcommand.
publish, to publish the application on the Azion platform.

Note: the step-by-step process to create a web application will be presented in the 3.2 Building a web application using Azion CLI from scratch tutorial. However, before that it’s important that you know the concept and technical details of each step individually. Read the following topics before practicing creating web applications with the CLI.

Initializing

The initialization process creates the environment necessary for building your web application. To do this, you must first:

Set the name of your web application.
Choose one of the three templates available in the CLI.
Initialize a JavaScript project with Node.js® ¹⁰ runtime environment.

The CLI currently provides three templates for building web applications:

JavaScript
Flareact
Next.js

Visit the framework sites at Flareact and Next.js for more information.

Note: the names of the templates listed above are the originals of the JavaScript language and the Flareact and Next.js frameworks. To initialize your web application, you must replace them in the CLI init command with javascript, flareact, or nextjs, respectively.

For now, the commands presented below are for information only. We suggest that you study the concepts and practices presented in this topic, without trying to execute them. You’ll use all of them in practice when we actually create a web application in the 2.2. Creating a Web application topic.

The init command initializes a web application with the following syntax:

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

Note: the --name and --type flags aren’t required. If they aren’t informed, the CLI will use the name set in your package.json, and the type will be auto-detected. In case you inform the name, your package.json will be updated.

If there is no package.json configuration file in your web application directory, the CLI will give the following error message:

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

In that case, create a package.json configuration file for your project in the same directory as your web application. Then rerun the command in order to initialize the application.

Tip: the best solution for creating a package.json file is to start a Node.js project in your web application directory. To do so, use the command below from the Node.js runtime environment:

npm init -y

Command response in 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"
}

In the example above, the command was executed in the web-app-proj folder of the web application. Note that the package.json file created has a key “name” with the value “web-app-proj”, which is the name of the folder created to store the web application. Also, the “main” key establishes that the project’s execution file is the index.js file.

If you choose to create the package.json file manually, remember to create the respective keys and values that suit your project specifically.

Note: the -y flag is optional. If you want to answer the npm package installer questions during the project build process, do not include this flag. For example, you could change the “name” key to a different value than the current project folder. If the -y flag is kept, all values in the package.json file will be set automatically.

After creating the Node.js project, type the ls command to confirm the creation of the package.json file.

Didn’t find what you were looking for? Open a support ticket.

Constructing

The second step in creating a web application is to build it based on the attributes provided in the init command. The command used to build the application is the build command, which has the following syntax:

azioncli edge_applications build

The build command doesn’t need any additional information to construct your web application. The --help flag is the only one available in the command, which displays a small help screen:

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

A requirement for using the build command is the presence of the webPack® ¹¹ framework installed on your computer.

Otherwise, the following error message will be displayed by the 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

In this case, remember to initialize a JavaScript project in your web application’s directory with the npm init -y command, which will automatically create the webPack framework files, in addition to other standard files. Then just run the azioncli edge_applications build command again.

Didn’t find what you were looking for? Open a support ticket.

Publishing

The final step in creating a web application is publishing it on the Azion platform. The publish command performs this task automatically with the following syntax:

azioncli edge_applications publish

Tip: the publish command executes internally and transparently to the developer, a build command. This way, it’s possible to create a web application with the CLI just by configuring it with the init commands and then publishing it with the publish command. However, we recommend using the build command during the development phase of your application in order to adjust the settings before publishing it on the Azion platform.

Now that you’ve followed the configuration details for your web application, you can follow the steps in the next topic to actually create it. With the concepts presented so far, you’ll follow the process in a direct and safe way.

Didn’t find what you were looking for? Open a support ticket.

Building a web application using Azion CLI from scratch

This tutorial will cover all the necessary steps to create a web application using the Azion CLI commands.

Requirements: Before starting to build your web application, you need to:

Create a folder on your computer’s file system, in which the web application will be stored. It can be located anywhere you like.
Download and install the Node.js JavaScript runtime compatible with your operating system from the official website; this installation includes the npm package manager.
Download and install the Azion CLI, version 0.46.0 or higher, as presented in the Installing topic.
Create a Personal Token on RTM and configure it in CLI. See the Authorization on the Azion Platform topic.

To create a web application using the CLI, follow these steps:

Create a folder on your computer’s file system with the name of your application; for example: my-web-app.

Note: your application folder can be anywhere you like.

Tip: you can create a folder on your file system directly using the terminal. To do so, run the command mkdir my-web-app, where my-web-app is the name of the folder.
Open the terminal on your computer and navigate to the web application folder with the cd /<path>/my-web-app command, for example.

Tip: you can open the terminal directly in the folder of your web application in a simple and practical way. To do this, open your computer’s operating system file manager, locate your web application’s folder, in this case my-web-app, and drag it over the terminal application icon on your computer. This tip works on most operating systems.
Run the following command to verify that the Azion CLI is correctly installed:

azioncli --version

CLI response, which may be different depending on the version of Azion CLI installed on your computer:
```
     azioncli version 0.46.0
```
Note: the azioncli version must be 0.46.0 or higher. If necessary, follow the steps to reinstall the CLI on the Installing topic.
Start a Node.js project in the application’s folder with the command:

npm init -y

The command creates a file called package.json in the same directory as the web application, which will be the project’s configuration file.

CLI response:
```
 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"
 }
```
Note: in the Wrote to /Users/… line of the above message, <user_name> is your username on the computer’s operating system, and <project_folder> is the folder chosen by you to archive your web application project. Instead of creating a new Node.js project, you can use an existing one.
Create a file named index.js in the same folder as the project with the following command:
```
 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
```
Note: copy all the lines of the above command, from the word echo to index.js, and paste it in the terminal. Then simply press ENTER or RETURN to execute the command, without changing it. The index.js file will be created with the JavaScript code from the example.

If desired, you can replace the code in the index.js file with one of your own.

Warning: remember to save the index.js file in plain text format, without any style formatting or special characters. Use a pure text editor of your choice for this. Otherwise, special and hidden characters may be included in the file without you noticing, compromising the function contained in the file in the future. Basically, avoid text editors that allow you to include any extra features besides text, like styles, images, and tables, for example.

Run the command:

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

 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%     

Tip: to examine the contents of the azion folder created by the edge_applications init command, type the command ls azion/, without leaving the current application directory. The following files will be displayed:

    README.md		azion.json		config.json		webdev.env		webpack.config.js

Run the command:

azioncli edge_applications build

The CLI responds with the following message on the monitor:
```
 Building your Web Application
 Your Web Application was built successfully
```
Note: the azioncli edge_applications build command may return the following error message:
```
 zsh: permission denied: azion
```
In this case, either the Personal Token is non-existent or it’s expired. You must then configure a new token to authorize the azioncli edge_applications build command on the Azion platform. To do this, create a Personal Token in RTM and then run the command, replacing the <my_personal_token> field with the new token:

azioncli configure --token <my_personal_token>

A token is a random string of characters of the form azionxxxxxxxxxxx.

CLI response:
```
 Token saved in /Users/<user_name>/.azion/credentials
```
Note: <user_name> is the user’s default directory on the computer’s file system.

See procedures for creating and managing personal tokens in the reference documentation.

Run the command:

azioncli edge_applications publish

The CLI response will be similar to the example below:

 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	

Copy the URL that appears at the end of the message from step 11, represented in this example by the string xxxxxxxxxx.map.azionedge.net; the characters “x” are alphanumeric and random.
Paste the URL into your web browser’s address bar.
Press the ENTER or RETURN key; you’ll see the following message on your browser screen: Congratulations! This is your web application on Azion!

Note: publishing a web application via RTM or CLI isn’t an instantaneous process. There’s a time to propagate and configure the application in Azion’s edge locations. It may be necessary to wait a few minutes for the URL to be activated and the application page to be effectively displayed in the browser.

Note that, in addition to automatically creating a URL for your application, the CLI presents other information at the end of the publish subcommand, as can be seen in the answer to step 11. The most important are:

Created Edge Function with ID 7026 - CLI has created a new Edge Function with ID 7026.
Created Edge Application with ID 1663959737 - CLI has created a new Edge Application with ID 1663959737.
Updated Rules Engine with ID 130309 - the CLI has updated the Rule Engine with ID 130309.
Created Domain with ID 1663956565 - the created domain, whose URL appears at the end of the message in step 11, and which can be used to open your web application in the browser.

Browse RTM to see the new elements that the CLI commands created in this 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.

Tip: if you want to retrieve your application’s URL, access Products Menu > Domains. You’ll see a list of your domains, including those created by the CLI commands.

In this guide you created a complete web application using only Azion commands CLI.

Reference guide

For a complete list of Azion CLI commands, subcommands, and flags, visit the CLI reference guide.

Didn’t find what you were looking for? Open a ticket.