Fork me on GitHub
Install awly & start local server

Option 1: Run Awly with npx

The easiest way to create your Awly project is to create an empty folder and inside run the command:

npx awly init

This will install the awly-cli locally with npm, download the default bootstrap awly project and start the localhost server.

Note that you will then have to run every awly cli command prefixed with npx.

Option 2: Install Awly as a global npm module

To use Awly as a global npm module you have to use the --unsafe-perm when installing like so:

sudo npm i awly -g --unsafe-perm

This will make the awly-cli commands available without the use of npx and you can invoke them for example like this:

awly serve

To create a new awly project make an empty directory and run: awly init inside.

Code editor

The recomended code editor is Atom together with the MarkoJS plugin which provides syntax highlighting for MarkoJS templates. To install it, go to Edit -> Preferences -> Install, search for language-marko and click install.

Project folder structure

In your project folder the structure will look like this:

Awly folder structure

For starting out the most important folder is the "src" folder. Inside this folder are all the parts to construct a web page.

Each web page is represented as a subfolder in the "src/pages". Your website URLs can be completely different to the folder names so the mapping is defined in the "project-config/routing.js" file. Both paths for normal pages as well as for API endpoints are in this file.

Create a new page with the Awly CLI

To create a new page you can use the awly page-create CLI command for example:

awly page-create contact

This will create:

  • a new page folder named "contect" in the "src/pages" directory
  • blank page template file named index.marko inside that folder
  • a record for "/contact" in the "project-config/routing.js"

To create a page folder but have it under different URL you add the URL as the second argument to the CLI comand slike so:

awly page-create howto /how-to

Eventhough the routing.js file gets generated by the page-create command you can still edit it by hand. To change the URLs of the pages for example.

Make a static HTML page with MarkoJS templating engine

Awly uses the MarkoJS framework to be able to compile web components into server side part and client side part. How to work with the MarkoJS syntax please take a look at its documentation at

If the component is not having any backend functionality there are no differences in the component syntax.

Working with dynamic data

Awly extends the MarkoJS framework in a way that it introduces two new code blocks in its component syntax:

  • server {...}
  • server-static {...}

Those code blocks only get compiled on the server side. You would usually include your backend code like DB connections, cookie handling, etc. there. To get more insight into that concept you can take a look at the src/components/vendor/awly/awly-list/index.marko component. This component can be also found here.

Feedback welcome

Awly is a very young framework and still in the making. So if you have any questions or suggestions please join the gitter channel where I will try my best to help you.