DEV Community: Aman Virk

Learn how to generate unique post slugs in Node.js

Aman Virk — Mon, 28 Jun 2021 08:31:30 +0000

I recently released a package called lucid slugify which helps you generate unique slugs from your Lucid models.

In this video, I share the reasoning behind creating this package and also how you can use the package in your AdonisJS apps.

Creating responsive emails using MJML and AdonisJS

Aman Virk — Mon, 14 Dec 2020 08:27:48 +0000

I have been using MJML for a while to design the email templates for my projects.

In the following video I share my process of using it along side AdonisJS.

Introducing AdonisJS - Database setup

Aman Virk — Tue, 24 Nov 2020 07:19:09 +0000

Let's talk about data. In this post, we will set up Lucid (AdonisJS SQL ORM) and make use of the migrations to create the necessary database tables.

Prerequisite

This article assumes that you already have some SQL database server setup on your computer and you know how to create a database manually.

If this is not the case, then I recommend using the sqlite database during the setup process. SQLite is a file-based database and doesn't anything else other than the sqlite3 npm package.

Lucid setup

Like always, the first step is to install the package from npm by running the following command.

npm i @adonisjs/lucid@alpha

Once done, run the following command to set up the package.

node ace invoke @adonisjs/lucid

The ace invoke command executes the instructions Javascript file exposed by the package.

I decided to go with the PostgreSQL database. You can choose any of the available databases.
Right after the setup command is completed, we need to copy the code for validating the environment variables to the env.ts file. Since environment variables are injected from the outside, AdonisJS recommends you validate them and ensure that your app is always running with the correct set of configuration values.
The config/database.ts file holds all the configuration related to the database.
Finally, the config file relies on the environment variables and you can update them inside the .env file. My values are

  PG_HOST=localhost
  PG_PORT=5432
  PG_USER=virk
  PG_PASSWORD=
  PG_DB_NAME=todo

Database Overview

Before we start writing any code, let me give you a brief overview of the AdonisJS data layer. We ship with an in-house ORM (Lucid) to work with the SQL databases.

Along with the support for all major SQL databases, the following are some of the hand-picked features of Lucid.

Active record ORM: The data models of Lucid follows the Active record pattern to simplify the database interactions. All the base level features including CRUD operations, relationships, serializing models to JSON are covered.
Database query builder: The database query builder is built on top of knex and allows you to construct SQL queries using the Javascript methods.
The database query builder is one level down from the data models, meaning the queries you write are sent as it is to the database driver without any modifications. This is usually helpful when you are writing complex queries that model high-level API cannot construct for you.
Schema migrations: Migrations allow you to create and evolve your database schema using code. It also comes with an inbuilt tracking system, so that every migration file is executed only once.
Model factories: Factories allows you to create/persist data models using fake data. They are usually helpful when writing tests or when seeding a database with some initial set of records.
Seeders: Database seeders can be used with or without factories to seed the database. For example, I will use factories to seed random data during development and may have a couple of seeders with real data like list of countries that should be in the database before deploying the app.

Schema migrations

As covered in the overview section the schema migrations allow us to create the database schema using code. So let's create the tables we need for our todo app.

Creating the categories table

node ace make:migration categories

# CREATE: database/migrations/1606195827305_categories.ts

Open the newly created file and paste the following code snippet inside it.

import BaseSchema from '@ioc:Adonis/Lucid/Schema'

export default class Categories extends BaseSchema {
  protected tableName = 'categories'

  public async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable().primary()
      table.string('name', 200).notNullable()
      table.string('slug', 200).notNullable().unique()
      table.string('color_code', 6).notNullable()
      table.timestamps()
    })
  }

  public async down() {
    this.schema.dropTable(this.tableName)
  }
}

The migration file has two methods. The up method is used to perform an action that is executed during the node ace migration:run command.
The down method should undo the action taken inside the up method. If the up method creates a table, then the down method should drop the table.
In the above migration file we are creating the categories table with a total of four columns
- The auto-increment id
- The category name
- The category slug. It is the URL friendly version of the category name
- And finally a color code. This is just to enhance the UI.

Let's run this migration by executing the following ace command. Also, make sure that you have manually created the database first.

node ace migration:run

# migrated database/migrations/1606195827305_categories
# Migrated in 173 ms

If you re-run the same command, you will get the following message.

node ace migration:run

# Already up to date

This is because Lucid tracks the migration files and do not re-run them. However, during development you can rollback your changes using the following ace command.

node ace migration:rollback

Creating the todos table

Let's repeat the same process for creating the todos table.

node ace make:migration todos

# CREATE: database/migrations/1606197725778_todos.ts

Open the newly created file and paste the following code inside it.

import BaseSchema from '@ioc:Adonis/Lucid/Schema'

export default class Todos extends BaseSchema {
  protected tableName = 'todos'

  public async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable().primary()
      table
        .integer('category_id')
        .unsigned()
        .notNullable()
        .references('id')
        .inTable('categories')

      table.text('title').notNullable()
      table.boolean('is_completed').notNullable().defaultTo(false)
      table.timestamps()
    })
  }

  public async down() {
    this.schema.dropTable(this.tableName)
  }
}

In the todos migration file, we define a foreign key constraint on the category_id at the database level.

Finally, run the following command to create the todos table.

node ace migration:run

# migrated database/migrations/1606197725778_todos
# Migrated in 159 ms

Data models

Data models are ES6 classes, where each class is responsible for interacting with a single database table. For our application, we will need two data models - one for the todos table and another one for the categories table.

Also, I want to mention - Models and migrations are not inter-connected, they are two separate tools that performs different tasks. You can have data models without migrations and vice-versa.

Creating the `Category` model

Run the following command to create a model for the categories table.

node ace make:model Category

# CREATE: app/Models/Category.ts

Open the newly created file and paste the following code inside it.

import { DateTime } from 'luxon'
import { BaseModel, column } from '@ioc:Adonis/Lucid/Orm'

export default class Category extends BaseModel {
  @column({ isPrimary: true })
  public id: number

  @column()
  public name: string

  @column()
  public slug: string

  @column()
  public colorCode: string

  @column.dateTime({ autoCreate: true })
  public createdAt: DateTime

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  public updatedAt: DateTime
}

The first thing is you have to define all the table columns on your models and apply the @column decorator to them. This helps Lucid distinguish between the standard model properties and the table columns.
The data types next to the column name are the Typescript data types. We are not dealing with database types like varchar here. For Typescript, there is nothing called varchar.
Finally, we allow you to use camelCase property names inside your models and during the SQL queries, we will convert them to snake_case. For example: The colorCode will become color_code.

Creating the todos model

Let's create the model for the todos table and set up the relationship between the Todo and the Category models.

node ace make:model Todo

# CREATE: app/Models/Todo.ts

import { DateTime } from 'luxon'
import { BaseModel, column } from '@ioc:Adonis/Lucid/Orm'

export default class Todo extends BaseModel {
  @column({ isPrimary: true })
  public id: number

  @column()
  public categoryId: number

  @column()
  public title: string

  @column()
  public isCompleted: boolean

  @column.dateTime({ autoCreate: true })
  public createdAt: DateTime

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  public updatedAt: DateTime
}

Setting up the relationship

Following are the relationships between the todos and the categories.

Categories has many todos.
A todo belongs to a category.

You don't have to define the relationship on both ends. Simply define the one's that you will be using inside your app. For example, We will be using the Category model to fetch the related todos, and therefore we will only setup the hasMany relationship.

Open the app/Models/Category.ts file and add the following import statements.

import { BaseModel, column, hasMany, HasMany } from '@ioc:Adonis/Lucid/Orm'
import Todo from 'App/Models/Todo'

Next, define the relationship as a property on the class.

export default class Category extends BaseModel {
  // ....

  @hasMany(() => Todo)
  public todos: HasMany<typeof Todo>
}

Demo time

With everything in place. Let's fire up the AdonisJS repl and run a few queries using our models.

node ace repl

To avoid too much typing, you can copy/paste the following code snippets inside the REPL session.

Load models by running the following method.
```
loadModels()
```

Create personal category

const personal = await models.Category.create({ name: 'Personal', slug: 'personal', colorCode: '4fd1c5' })

Create work category

const work = await models.Category.create({ name: 'Work', slug: 'work', colorCode: 'e53e3e' })

Add todo inside the work category

await work.related('todos').create({ title: 'Kick start "Introducing AdonisJS" articles series on dev.to' })

Add todo inside the personal category

await personal.related('todos').create({ title: 'Buy groceries when going back to home. Make sure to buy some chocolates too' })

You can open the database inside some GUI tool and verify that the rows are added to the respective database tables with correct foreign keys.

Introducing AdonisJS - Designing the web page

Aman Virk — Fri, 20 Nov 2020 07:42:55 +0000

Alright, let's begin designing the by web page for listing all of our todos, along with an input box to create a new one. In this post, you will learn about Edge layouts and components.

Layouts

Layouts are standard edge templates that expose the sections in which the children templates can inject their markup. Let's see them in practice.

Run the following ace command to create a new template.

node ace make:view layouts/master

# CREATE: resources/views/layouts/master.edge

The master.edge file is created inside the layouts directory. Again, this is just a convention and not a technical limitation to keep the layouts inside this directory.

Open the newly created file and paste the following code snippet inside it.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <link rel="stylesheet" href="/css/styles.css" />
    <script src="/js/app.js" defer></script>
  </head>

  <body class="h-screen font-sans">
    <div class="max-w-lg m-auto">
      <header class="py-16">
        <div class="mb-4">
          <svg width="99" height="33" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M57.19 13.304h-3.653v12.28h-3.063v-12.28H48v-2.77h2.474V8.55c0-1.322.422-2.401 1.266-3.238.864-.855 1.974-1.283 3.328-1.283.786 0 1.434.146 1.944.438.53.291.913.573 1.149.846l-1.03 2.304a2.92 2.92 0 00-.767-.525 1.922 1.922 0 00-.942-.263c-.707 0-1.198.165-1.473.496-.275.33-.412.739-.412 1.225v1.983h3.652v2.771zm3.18 12.28V4h3.034v21.583H60.37zM80.657 10.27v15.313h-3.063v-2.362c-.471.642-1.168 1.244-2.091 1.808-.923.564-1.993.846-3.21.846a6.552 6.552 0 01-3.564-1.02c-1.06-.681-1.905-1.624-2.533-2.83-.628-1.206-.943-2.586-.943-4.142 0-1.555.324-2.926.972-4.112.648-1.206 1.542-2.14 2.68-2.8 1.14-.68 2.435-1.021 3.888-1.021 1.08 0 2.022.233 2.828.7.824.467 1.482 1.011 1.973 1.633v-2.012h3.063zm-7.658 12.834c.943 0 1.767-.223 2.474-.67a4.768 4.768 0 001.65-1.867c.392-.798.589-1.692.589-2.684 0-.972-.197-1.847-.59-2.625a4.557 4.557 0 00-1.649-1.837c-.707-.467-1.531-.7-2.474-.7-.903 0-1.708.223-2.415.67a4.555 4.555 0 00-1.65 1.838c-.392.778-.588 1.663-.588 2.654 0 .992.196 1.886.589 2.684.393.777.942 1.4 1.65 1.866.706.448 1.511.671 2.414.671zM91.784 10.008c1.375 0 2.602.34 3.682 1.021 1.1.661 1.963 1.585 2.592 2.771.628 1.186.942 2.557.942 4.113 0 1.536-.314 2.906-.942 4.112-.629 1.186-1.483 2.12-2.563 2.8-1.08.68-2.287 1.02-3.622 1.02-1.1 0-2.101-.232-3.005-.7-.883-.466-1.58-1-2.09-1.603V32h-3.064V10.242h3.063v2.245c.452-.641 1.13-1.215 2.033-1.72a5.986 5.986 0 012.974-.759zm-.412 2.771c-.923 0-1.748.224-2.474.671a4.77 4.77 0 00-1.679 1.838c-.392.758-.589 1.633-.589 2.625 0 .972.197 1.847.59 2.625a5 5 0 001.678 1.866c.726.447 1.551.671 2.474.671.923 0 1.738-.224 2.444-.67a4.767 4.767 0 001.65-1.867c.412-.778.618-1.653.618-2.625 0-.992-.206-1.867-.618-2.626a4.554 4.554 0 00-1.65-1.837c-.706-.447-1.521-.67-2.444-.67z" fill="#000"/><path d="M7.832.904a3.949 3.949 0 00-3.591 3L.923 17.422v11.226a3.948 3.948 0 003.948 3.949h27.734a3.948 3.948 0 003.949-3.949V16.926L33.456 3.93a3.948 3.948 0 00-3.84-3.033h-.068v3.948h.068l2.99 12.545v11.258H4.87V17.9L7.832 5.835V.905z" fill="#5A4FD6"/><path d="M18.69 24.587a5.925 5.925 0 005.586-3.948H34.78V16.69H20.664v1.974a1.974 1.974 0 01-3.948 0V16.69H2.778v3.949h10.327a5.925 5.925 0 005.585 3.948zM28.561 8.793H8.82v3.949h19.742V8.793zM26.587 2.87H10.794v3.95h15.793V2.87z" fill="#5A4FD6"/></svg>
        </div>

        <p class="text-gray-600 text-xl font-normal">
          <a
            href="https://dev.to/amanvirk1/introducing-adonisjs-28af"
            class="text-gray-900 underline"
            >Follow along</a
          >
          as we build this todo app using AdonisJS, TailwindCSS and Alpine.js.
        </p>
      </header>

      @!section('body')
    </div>
  </body>
</html>

The keywords starting with @ are called tags in Edge. For example The @layout tag, the @section tag, and so on.
The master.edge file defines the markup that will remain the same on all the pages.
Also it creates an empty section @!section('body'), that children templates can inject their markup into and that will be placed right after the header.

To give it a try, let's open the todos/index.edge file we created in the last post and replace all of its content with the following code snippet.

@layout('layouts/master')

@section('body')
  <h1>Todos</h1>
@endsection

Using the @layout tag, we tell edge about the layout we want to use.
Next, we use the @section tag to inject our markup. The section names needs to be the same inside this file and the layout file.
Anything outside the section tag will be ignored as Edge doesn't know where to place that markup.

Let's start the development server by running node ace serve --watch and node ace mix:watch commands and view the webpage in the browser.

Tweaking styles

Great. Let's take a step further and update the tailwindcss config to define our own set of colors and shadows. Open the tailwind.config.js file and replace its contents with the following code snippet.

module.exports = {
  purge: ['./resources/views/**/*.edge'],
  theme: {
    colors: {
      transparent: 'transparent',
      white: '#fff',
      gray: {
        900: '#24272e',
        700: '#64697e',
        600: '#7d849c',
        200: '#d2d5df',
        100: '#eff0f4',
      },
    },
    boxShadow: {
      default: '0px 1px 14px rgba(0,0,0,0.08)',
      sm: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
    },
    extend: {
      margin: {
        0.5: '0.125rem',
      },
      fontFamily: {
        sans: ['Nunito Sans', 'sans-serif'],
      },
    },
  },
  variants: {
    boxShadow: ['hover', 'focus', 'focus-within'],
    backgroundColor: ['hover', 'focus', 'focus-within'],
  },
}

I have defined my own set of colors and box shadows. If you notice, they are outside of the extend object. It means, we are not extending the tailwind config, instead are completely overwriting it.
Next, I extend the margin utilities to have a m-0.5 class and use Nunito Sans as the main font family.
I want tailwindcss to generate box-shadow and background color classes for hover, focus, and focus-within states.
Finally, we want the purgeCSS to scan our edge templates and remove the unused CSS. You can learn more about it in the tailwindcss docs.

Let's import the Nunito Sans font from Google fonts. Open the resources/css/styles.css file and add the following file of code to it.

@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:ital,wght@0,300;0,400;1,600&display=swap');

Also, I want to give the body a gradient background, so let's add that too in the same file.

body {
  background: #d7dceb;
  background: -webkit-linear-gradient(to right, #d7dceb, #e2e2e2);
  background: linear-gradient(to right, #d7dceb, #e2e2e2);
}

Components

To begin with, do not confuse Edge components with Web components or even with React or Vue components.

Components in Edge means a piece of a template that has its isolated state from the rest of the template. However, they do allow:

Passing props to them
Defining slots to inject markup to the component body
And a component is capable of sharing data with the component caller

Do remember all this is happening on the server-side. Edge is not a frontend template engine.

We will be creating a total of three different components.

A component to render the markup for a single todo.
A component to display the input box for creating a new todo.
Finally, one for the dropdown to filter todos by their list. This one will also use Alpine.js to show/hide the dropdown.

Dropdown component

Let's begin with the dropdown component first. Run the following command to create a new template.

node ace make:view components/dropdown

# CREATE: resources/views/components/dropdown.edge

Open the newly created file and paste the following code snippet inside it.

<div
  class="bg-gray-200 rounded py-2 px-4 focus-within:bg-white focus-within:shadow relative"
  x-data="{ opened: false }"
  @click.away="opened = false"
>
  <a href="#" class="flex items-center" @click.prevent="opened = !opened">
    <span class="mr-2">
      {{ items.find((item) => item.id === selected).text }}
    </span>
    <svg class="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path></svg>
  </a>

  <div
    class="bg-white shadow absolute whitespace-no-wrap left-0 rounded py-3 mt-1 w-40"
    x-show="opened"
  >
    @each(item in items)
      <a
        href="{{ item.url }}"
        class="text-gray-700 flex py-1 items-center px-4 hover:bg-gray-100"
      >
        <span
          class="w-3 h-3 rounded mr-2 border-2"
          style="border-color: {{ item.color }}"
        >
        </span>
        {{ item.text }}
      </a>
    @endeach
  </div>
</div>

We have a standard markup with tailwind classes to style the elements.
The component needs an array of items for the dropdown list. Every item inside the array is an object with the following properties.
- id: A unique identifier for the item
- text: The display text
- color: Just for beautifying the list
- url: The URL to visit on click.
Finally, it needs a selected prop to know the selected item from the list.
Also we have added the alpine attributes to make the component functional. If you are new to alpine, then I recommend spending some time reading the README file.

Let's use this component inside the todos/index.edge file.

@section('body')
  <div class="flex justify-between">
    <div class="mr-3">
      @!component('components/dropdown', {
        selected: 'all',
        items: [
          {
            id: 'all',
            url: '?list=all',
            text: 'All',
            color: '#999',
          },
          {
            id: 'personal',
            url: '?list=personal',
            text: 'Personal',
            color: '#4fd1c5',
          },
          {
            id: 'work',
            url: '?list=work',
            text: 'Work',
            color: '#e53e3e',
          },
        ]
      })
    </div>
  </div>
@endsection

The @component tag accepts the path to the component template, along with a props object.
For now, we are hardcoding the list items. Later we will get it from the database.

Demo time 😎

Input component

Let's repeat the same process and create another component for the input box to create a new todo.

node ace make:view components/input

# CREATE: resources/views/components/input.edge

<div class="bg-gray-200 rounded py-2 px-6 focus-within:bg-white focus-within:shadow flex-1">
  <input
    type="text"
    name="{{ name }}"
    id="{{ name }}"
    value="{{ flashMessages.get(name) || value || '' }}"
    placeholder="{{ placeholder }}"
    class="bg-transparent w-full outline-none placeholder-gray-600"
  />
  @if(flashMessages.has(`errors.${name}`))
    <p class="text-sm">{{ flashMessages.get(`errors.${name}`) }}</p>
  @endif
</div>

The input component needs the input name, placeholder, and an optional value.
Ignore all the code related to flashMessages for now. I have added them to make the component future-ready and we will learn about flash messages later.

Let's also use this component inside the todos/index.edge file.

<div class="mr-3">@!component('components/dropdown', {... })</div>

<div class="flex-1">
  <form action="/todos" method="POST">
    @!component('components/input', {
      name: 'text',
      placeholder: 'Start typing to create a new todo',
    })
  </form>
</div>

Todo component

Let's wrap up by creating a component to show a single todo item.

node ace make:view components/todo

# CREATE: resources/views/components/todo.edge

<div class="flex text-gray-700">
  <div class="mt-0.5">
    <input
      type="checkbox"
      name="is_completed"
      class="block form-checkbox"
      {{ isCompleted ? 'checked' : '' }}
    >
  </div>

  <div class="px-3 leading-tight flex-1">
    <p>{{ text }}</p>
  </div>

  <a href="http://" class="mt-0.5 text-gray-600">
    <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"></path></svg>
  </a>
</div>

This time we just need the todo text and whether it's completed or not.
Later we will introduce some forms inside this component to mark the todo as done or to delete it.

Let's update the todos/index.edge file and use this component.

<div class="mt-6">
  <div class="bg-white rounded-lg shadow py-3 px-4 mt-3">
    @!component('components/todo', {
      text: 'Kick start "Introducing AdonisJS" articles series on dev.to',
      isCompleted: true,
    })
  </div>

  <div class="bg-white rounded-lg shadow py-3 px-4 mt-3">
    @!component('components/todo', {
      text: 'Buy groceries when going back to home. Make sure to buy some chocolates too',
      isCompleted: false,
    })
  </div>

  <div class="bg-white rounded-lg shadow py-3 px-4 mt-3">
    @!component('components/todo', {
      text: 'Record podcast. Ping Romain for same',
      isCompleted: true,
    })
  </div>
</div>

Introducing AdonisJS - Setup up Laravel mix

Aman Virk — Tue, 17 Nov 2020 07:36:13 +0000

In this post, we will learn how to use the AdonisJS template engine (Edge) and set up Webpack/Laravel mix to process TailwindCSS and Alpine.js.

Views & Templates

The official and the recommended template engine of AdonisJS is Edge. It is a logical template engine and comes with some neat features like:

An easy to write syntax
Support for conditionals, loops, layouts, and partials
Support for components (a personal favorite)
Allows runtime debugging using Chrome DevTools
Accurate stack traces

We won't be covering every feature of the edge in this series and just focus on the pieces we need for our todo app.

Rendering views

Open the start/routes.ts file and replace all of its contents with the following code snippet.

import Route from '@ioc:Adonis/Core/Route'

Route.get('/', 'TodosController.index')

Assuming you already have the TodosController from the previous post. Replace its contents with the following code snippet.

import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'

export default class TodosController {
  public async index({ view }: HttpContextContract) {
    return view.render('todos/index')
  }
}

The view.render methods takes the path to the template file stored inside the resources/views directory.
Adding a file extension is optional.
The return value is a string. In our case, it will be a string containing the final HTML.

You can also render views using the Adonis/Core/View module directly. For example:

import View from '@ioc:Adonis/Core/View'
View.render('todos/index')

However, there is a difference between using the module directly and using the ctx.view object.

The ctx.view object also contains the information about the current HTTP request like the request details, authenticated user, session flash messages and so on. Therefore it is recommended to always use ctx.view during an HTTP request.

Creating the view file

Let's create the todos/index.edge file using the following ace command.

node ace make:view todos/index

# CREATE: resources/views/todos/index.edge

Open the newly created file and paste the following contents inside it.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
  </head>

  <body>
    <h2>Todos app</h2>
    <p>We will being rendering todos here</p>
  </body>
</html>

Finally, visit the http://localhost:3333 URL to view the rendered HTML.

Serving static assets

Everything we have done so far is on the server-side. However, we do need some way to style our webpages using CSS and also write front-end JavaScript to make the pages interactive.

Let's start with the basics and slowly move towards using a build tool like Webpack to bundle the front-end assets.

To begin with, we need some way to serve CSS and JavaScript files to the browser. In AdonisJS, you need to keep these files inside the public folder and then access them using the relative path. Let's give it a try.

Create a new file named styles.css inside the public directory and paste the following contents to it.

body {
  background: #d7dceb;
  background: -webkit-linear-gradient(to right, #d7dceb, #e2e2e2);
  background: linear-gradient(to right, #d7dceb, #e2e2e2);
}

Now, visit http://localhost:3333/styles.css to access the file inside the browser.

Great! Lets open resources/views/todos/index.edge and load this css file.

<head>
  <!-- Other tags -->
  <link rel="stylesheet" href="/styles.css" />
</head>

The same process can be repeated for JavaScript files, images, fonts, and so on.

Using assets bundler

In the previous section, we accomplished the task of serving static files by adding them to the public folder. Of course, these files have to be written in a way that browsers can understand, parse, and execute.

However, we live in a complicated world. We are so much used to using pre/post processors. Writing code that browsers cannot fully understand. Therefore we need tools like Webpack to compile our version of code into something different browsers can understand.

Using Laravel Mix

The Laravel community (Jeffrey Way to be specific) created Laravel mix which wraps webpack into a high level, less verbose API. Even though the package uses the keyword Laravel, it can be used independently as well.

Luckily, there is also a package for AdonisJS that eases the setup process of using Laravel mix in AdonisJS apps.

So let's start by installing it.

npm i --save-dev adonis-mix-asset laravel-mix@next

Run the following command to configure the package.

node ace invoke adonis-mix-asset

# CREATE: webpack.mix.js
# UPDATE: .adonisrc.json { commands += "adonis-mix-asset/build/commands" }
# UPDATE: .adonisrc.json { providers += "adonis-mix-asset" }
# CREATE: ace-manifest.json file

And start the compilation process by running the following ace command. Also, feel free to reference the README file of the adonis-mix-asset package.

node ace mix:watch

Setup TailwindCSS

We are all set now! Before giving this set up a test run let's also install and configure Tailwind CSS.

npm i -D tailwindcss

# Create a Tailwind config file
npx tailwindcss init

Open the webpack.mix.js file and add the following line of code inside it.

mix.postCss('resources/css/styles.css', 'public/css', [require('tailwindcss')])

Here we tell mix to process the resources/css/styles.css file using PostCSS.
The output should be written to the public/css folder.
Also, we are using tailwind as a plugin of PostCSS.

Why resources folder and not public?
If you noticed we are telling PostCSS to read the file from the resources/css folder and not the public folder.

The PostCSS syntax is not something the browsers can understand and hence there is no point in keeping this file inside the public folder. Instead, we want the processed output to be in the public folder.

This is true for every other file including the frontend JavaScript, images, and so on. Any asset that needs pre-processing should not be in the public folder.

Let's remove everything we added to the public folder earlier.

rm -r public/*

Create a new file named css/styles.css inside the resources directory and paste the following contents inside it.

@tailwind base;
@tailwind components;
@tailwind utilities;

Finally, we need to update our template to load the CSS file created by Laravel mix inside the public folder.

<link rel="stylesheet" href="/css/styles.css" />

Let's give it a try now. Run the following commands to start the HTTP server and the mix process.

# Starts AdonisJS server
node ace serve --watch

# Inside another terminal session
node ace mix:watch

Now open the webpage inside the browser and for sure you will see TailwindCSS getting loaded on the page.

Setup Alpine.Js

Let's quickly follow the same process for setting up Alpine.js. Begin by installing the package.

npm install alpinejs

Create a JavaScript file named app.js inside the resources/js directory and paste the following contents inside it.

import 'alpinejs'

Next, tell mix to pre-process this file by adding the following line of code to the webpack.mix.js file.

mix.js('resources/js/app.js', 'public/js')

Also, make sure to restart the node ace mix:watch command for the mix to pick up the config file changes.

Finally, we can load the processed JavaScript file inside the head tag.

<script src="/js/app.js" defer></script>

To give it a test run, modify the body tag as follows.

<body x-data="{}" x-init="() => alert('Alpine is ready')">
  <h2>Todos app</h2>
  <p>We will being rendering todos here</p>
</body>

Closing notes

Initially, I decided to even design the webpage in the post. However, we already covered a lot of ground, so let's move the design phase to the next post.

Today we learned about

Rendering views using the ctx.view.render method.
Server front-end assets by keeping them inside the public folder.
Setup adonis-mix-asset to process the front-end assets and write them to the public folder.

Introducing AdonisJS - Routes & Controllers

Aman Virk — Fri, 13 Nov 2020 08:32:08 +0000

Let's start dipping our toes in the code now by creating some routes and controllers.

For anyone unaware of the term routing. In terms of web development, it is a mapping of URLs and their handlers that you want your app to handle. URLs outside of this mapping will result in a 404.

Defining routes

Routes in AdonisJS are defined inside the start/routes.ts file. Using this file is a convention and not a technical limitation. Let's open the file and replace its contents with the following code snippet.

import Route from '@ioc:Adonis/Core/Route'

Route.get('/', async () => {
  return 'This is the home page'
})

Route.get('/about', async () => {
  return 'This is the about page'
})

Route.get('/projects', async () => {
  return 'This is the page to list projects'
})

We begin by importing the Route module.
Using the Route.get method, we define a total of 3 routes.
A typical route accepts a route pattern and a handler to respond to the requests.
In the above example, the handler is an inline function. Later we will look into using controllers as well.
Finally, the return value of the function is sent back to the client making the request.

Let's give this code a try by visiting the URLs for the registered routes.

Supported data types

You can return most of the Javascript data types from the route handler and AdonisJS will properly serialize them for you.

Route.get('/', async () => {
  // return 28
  // return new Date()
  // return { hello: 'world' }
  // return [1, 2, 3]
  // return false
  // return '<h1> Hello world </h1>'
})

HTTP Context

Every route handler receives an instance of the HTTP context as the first parameter. The context holds all the information related to the current request, along with the response object to customize the HTTP response.

Route.get('/', async (ctx) => {
  console.log(ctx.inspect())

  return 'handled'
})

Following is the output of the ctx.inspect().

If you are coming from a framework like express, then there is no req and res objects in AdonisJS. Instead you have access to ctx.request and ctx.response.

Also note that the API of request and response is not compatible with express and neither it is a goal for us.

The HTTP context has an extendible API and many AdonisJS packages add their properties to the context. For example: If you install the @adonisjs/auth module, it will add the ctx.auth property.

Using controllers

Controllers in AdonisJS are vanilla ES6 classes stored inside the app/Controllers/Http directory. You can create a new controller by running the following ace command.

node ace make:controller TodoController

# CREATE: app/Controllers/Http/TodosController.ts

Let's open the newly created file and replace its contents with the following code snippet.

import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'

export default class TodosController {
  public async index(ctx: HttpContextContract) {
    return 'Hello world from the todos controller'
  }
}

How should we now go about using this controller inside our routes file?
Let's begin with zero magic and simply import the controller inside the routes file. Open the start/routes.ts file and add another route using the controller.

import Route from '@ioc:Adonis/Core/Route'
import TodosController from 'App/Controllers/Http/TodosController'

Route.get('/todos', (ctx) => new TodosController().index(ctx))

Visit the http://localhost:3333/todos URL and you will surely see the return value from the controller method.

Lazy loading controllers

Now, imagine an app with 40-50 controllers. Every controller will also have its own set of imports, making the routes file a choke point.

Lazy loading is the perfect solution to the above problem. Instead of importing all the controllers at the top level, we can lazily import them within the route's handler.

import Route from '@ioc:Adonis/Core/Route'

Route.get('/todos', async (ctx) => {
  const TodosController = (await import('App/Controllers/Http/TodosController'))
    .default
  return new TodosController().index(ctx)
})

Now, the TodosController is only loaded when the request for the /todos route comes in. Since the import/require statements are cached in Node.js, you don't have to worry about reading the same file multiple times from the disk.

Are are you happy with the above code?
I am personally not. There is too much boilerplate and you would expect a framework to do a better job here and cleanup things for you and AdonisJS does that.

Replace the previously written route with the following code snippet.

Route.get('/todos', 'TodosController.index')

This is the recommended way of referencing controllers within your routes file.

We already know that your controllers are inside the app/Controllers/Http directory and hence there is no need to define the complete path.
You only need to define the file name and the method to be called on the exported class.
Behind the scenes, AdonisJS will lazily import the controller. Creates an instance of it and executes the referenced method.

What about the type safety?
The verbose implementation has the extra benefit of being type safe. This is something missing when using the string based expression. Or I will say, it is missing for now.

We need two things to achieve type safety when referencing controller.method as a string expression.

The ability to tokenize the expression and create a full path to the controller and its method. This is achievable with Typescript 4.1 beta release. Here is a proof of concept for the same.
Next is the ability to have an Import type with support for generics. There is an open issue for it and I am positive that it will make its way to the Typescript in the future, as it adheres to the Typescript design goals.

To summarize, we bet in the future of Typescript and decided to remove all the extra boilerplate required to reference controllers within the routes file and expose a simple to use API.

Wrap up

Alright, let's wrap up this post. In the next post, we will begin designing the web page for our todo app.

Meanwhile, lemme share some code examples for commonly required tasks that you may perform when creating a web app.

Render views

Render views using the AdonisJS template engine

Route.get('todos', async ({ view }) => {
  return view.render('todos/index', {
    todos: [{ id: 1, title: 'Writing an article', isCompleted: false }],
  })
})

Modify outgoing response

Route.get('/', async ({ response }) => {
  response.redirect('/to/a/url')
  response.status(301)
  response.header('x-powered-by', 'my-app-name')
  response.cookie('foo', 'bar')
})

Stream files from the disk

Route.get('/', async ({ response }) => {
  response.download('/path/to/some/file.txt')
})

Read request data

Route.get('/', async ({ request }) => {
  console.log(request.url())
  console.log(request.method())
  console.log(request.cookie('cookie-name'))

  // request body + query string
  console.log(request.all())

  // get a single file & validate it too
  const avatar = request.file('avatar', {
    size: '2mb',
    extnames: ['jpg', 'png', 'jpeg'],
  })

  // All uploaded files as an object
  console.log(request.allFiles())
})

Introducing AdonisJS - Part 3

Aman Virk — Thu, 12 Nov 2020 07:39:04 +0000

We got up and running with a new application in the previous post. In this post, lets will take a step ahead and learn about some of the key concepts of AdonisJS.

I think it is very important to know about your tools before you starting using them. So let's spend another post without writing any code.

Ace commands

In this last post, we start the development server by running the node ace serve --watch command, so let's start by breaking it down

node is the node binary installed on your computer.
ace is a Javascript file in the root of your project. We removed the .js extension, coz it is easier to type node ace over node ace.js
After the ace keyword is the command name and the arguments/flags required by the command.

Why the hell did not create a command-line binary that can be installed globally?
You might be thinking, why there isn't a command-line binary that can be installed globally and then use it as follows

adonis serve --watch
adonis make:controller <Name>

# and so on

The answer is, you cannot have project-specific commands with a global binary and a backend server usually needs project-specific commands. For example:

A command to run queue workers
A command to migrate the database
Or maybe if you play fancy, then command to set up the project by creating an admin user and seeding data.

AdonisJS is not the first one to do this. Django has manage.py file. Laravel has an artisan file. However, when looking at the Node.js landscape, the concept feels a bit alien, hence requires explanation.

Directory structure

The default project structure of AdonisJS contains a bunch of files and folders by default. You may get overwhelmed at first by looking at the directory structure, especially when you are new to the framework. So, let's go ahead and talk about the important files and folders.

The `.adonisrc.json` file

The .adonisrc.json is one of the most important files as it is responsible for configuring your project and workspace.

Even though the file contains the bare minimum config by default. It allows overriding almost every convention used by the framework.

Run the following command to see the complete set of available options and their pre-configured defaults.

node ace dump:rcfile

About Fx fx is a commandline utility to make the JSON output interactive

The `server.ts` file

The server.ts file is the entry point of your HTTP server. Running this file directly will boot your application and then starts the HTTP server.

This is a file you will run on your production server after it gets compiled to Javascript.

The `app` directory

The app directory contains most of your application code. HTTP controllers, middleware, models, services, and much more live inside this folder.

The `config` directory

The config directory is dedicated to storing all the configuration required by your app. By default, we create a handful of well-documented configuration files that are used by the framework core and first-party packages.

As your application will grow, you can also use this directory to store additional configuration files.

The `start` directory

The start directory contains all the files that you want to load only once during the application boot phase. We also call them preloaded files.

There is no technical limitation or hard coded rule that files inside this directory will be loaded only once. But more of a convention we follow to communicate a clear intent.

The `resources` directory

The resources directory is dedicated to storing edge templates inside a subdirectory called views.

It is also recommended to use this directory also for storing un-compiled frontend assets like SASS files or frontend JavaScript. After compiling the frontend assets, they must be moved to the public directory, since the resources directory is not exposed to the internet.

The `public` directory

The public directory is exposed to the internet and all the files can be accessed by their path.

Given the following files inside the public folder

public
├── app.js
├── logo.png
└── style.css

You can access them as

http://localhost:3333/app.js
http://localhost:3333/logo.png
http://localhost:3333/style.css

The `database` directory

AdonisJS recommends storing the database schema migrations, seeders and factories inside the database directory.

We keep them outside of the app directory because they are usually not part of the runtime code and get executed as a separate step during development or pre-deployment.

Typescript first

AdonisJS is a Typescript first framework. Beyond using it as a marketing term, we have invested a lot in building first-class primitives for a better typescript experience. In a nutshell, it includes

First-class support for running Typescript source directly without compiling during development.
Inbuilt command node ace build to create a standalone build folder that can be deployed to the production server.
Support for static types for environment variables.
Data validator that extracts static types after performing the runtime validations.
Application-aware REPL that can compile and run the typescript code directly.

If you find value in adopting Typescript, then you can also bet on AdonisJS, as we are always looking for ways to fully embrace typescript.

Fully featured, not full-stack

AdonisJS is a fully featured and not a full-stack framework. The term full-stack is generally used when someone or something is equipped with both the web frontend and the backend.

AdonisJS has zero opinions on how you create your frontend.

Want to server render HTML? We got your back with a pretty decent template engine.
Want to use React, Vue, or Svelte? Use AdonisJS to create a JSON API and then develop your frontend as an independent app consuming the API
Want to develop a Mobile app? Again, consume the same API and build a native mobile app

A lot of us think that if a framework is not full-stack, then it is a micro-framework. For god sake, there are a gazillion things that we do and should do on the backend. For example:

Managing the data layer wisely. It includes sanitizing data, hashing/encrypting values with secret keys, and a much more
User authentication and authorization
Sending emails
Queue jobs
Validations
Managing file uploads
Interacting with 3rd party APIs. No, you cannot connect with 3rd party APIs securely from your frontend app.
Payments & Subscriptions

A fully-featured framework like AdonisJS makes all this easy.

Introducing AdonisJS - Setup

Aman Virk — Wed, 11 Nov 2020 07:05:20 +0000

In this post, we will focus on setting up the development environment and also get our code editor ready to work with Typescript and Edge (the template engine of AdonisJS)

Prerequisites

AdonisJS is a Node.js framework and therefore you must have Node.js installed on your computer.

If it's not installed, then please head over to nodejs.org and download the binary/installer for your operating system. If you are comfortable with the command line, then I recommend using volta (personal favorite) or nvm for installing Node.js.

Check Node.js version

Make sure that the installed version is greater than 12.0.0 along with npm >= 6.0.0.

node -v
npm -v

That's all you need :)

Creating a new project

Creating a new AdonisJS project is pretty straight forward. All you need to do is run the following npm init command.

npm init adonis-ts-app todo

Here npm init is an npm specific command to install a package and run its bin command in one go.
The package name is create-adonis-ts-app, but npm init wants us to drop the create prefix. Not sure about the history behind this decision, but the yarn has the same design as well.
Finally todo is the path in the filesystem where you want to create the project. If the directory is missing, we will create it for you. However, if the directory already has files then we will refuse to create a project inside it.

Differences between the `web` and the `api` project structure

The project creation flow prompts you to choose between the api and the web project structure. The following are the differences between both.

The web project structure installs the template engine and the session package of AdonisJS. Also, the support for serving static files like CSS or images is enabled.
On the other hand, the api project structure configures the support for CORS.
Apart from these specific changes, the rest of the project structure and files are the same.

Starting the development server

Run the following command to start the development server. Make sure that you are inside the project root before running the command.

node ace serve --watch

Here things get a bit interesting. We will talk about ace commands in the next post. But for now, ace is a command-line framework that is embedded within your app and this allows you to create project-specific commands and run them using node ace.

The serve command starts the development server and the --watch flag continues watching the filesystem for changes and restarts the server after every change.
Also, the serve command can run the typescript source directly. There is no intermediate compilation step and this speeds up things a little bit.

VSCode setup

To begin with, I am going to share a list of extensions that you must install for VSCode. If you are not a VSCode user, then feel free to leave comments and I will update the blog post with other editors setup too.

The source code is written in Typescript and luckily VSCode comes with out of the box support it and hence no special plugins are required to work with Typescript.
You must install the Edge template support plugin to have syntax highlighting for the AdonisJS template engine (Edge).
If you don't hold strong opinions against prettier and eslint. Then I highly recommend VScode Eslint and VSCode prettier plugins to make your life a bit easier.

What's in the box?

Since AdonisJS is a fully-featured framework, you get a lot with a new application. The following features or functionality is baked right into the core of the framework.

HTTP stack. It includes the router, request & response objects, support for middleware, global exception handler.
Bodyparser and support for file uploads. Even stuff like directly streaming files to a third party like s3.
Validator to validate the request data.
Encryption and Hash modules with sensible defaults by keeping overall security in mind.
An embedded command line framework ace.
Support for encrypted/signed cookies and session.
Support for serving static files from the public directory.
And finally, a well thought project structure and out of the box support for typescript.

Closing thoughts

This post is mainly targeted towards the audience using AdonisJS or Node.js for the first time. I want to talk about every little detail without making assumptions that the reader already knows this.

If you think all this is a no-brainer for you, then stick around, things will get interesting as we will make progress 🙂

Introducing AdonisJS

Aman Virk — Tue, 10 Nov 2020 04:35:37 +0000

Hello everyone 👋. I am Aman Virk, the creator of AdonisJS (a fully-featured web framework for Node.js). Today I am starting a blog posts series to introduce you to the framework, where we together build a little todo app.

If you are someone who is just starting with Node.js or looking to explore a framework that you can use going forward, then I welcome you to follow the entire series and also become part of the AdonisJS community 🙂

Outline

Even though the app we are building doesn't have many features, this series will still get quite long, as I will be covering a lot of fundamentals initially.

The outline briefly looks as follows:

Introduction ( this post )
Setup
Get to know AdonisJS
Routing & Controllers
Creating & designing pages
Building frontend assets
Planning the todo app
ORM setup
Creating models & migrations
Using the AdonisJS REPL
Rendering todos
Creating a todo
Marking a Todo as done
Deleting a todo
Deploying to Digital ocean via Cleavr
Deploying to Digital ocean via App platform

Why AdonisJS?

This might be the first question you have in your mind. "Why should I even give AdonisJS a try?"

Luckily, answering this question is easy enough for me, since AdonisJS proposes a different paradigm for writing your web servers in Node.js. It's possible that you may or may not like the paradigm altogether, but the framework itself is unique enough to not cause any confusion for its existence.

The popular approach I have always witnessed in Node.js is to start with microframeworks like Express, Koa, or Fastify and then build things on top of it. Even the basic stuff like parsing the request body, validating forms, the logger has to be pulled in separately and AdonisJS is the opposite of this.

Philosophically AdonisJS follows the approach of Laravel, Ruby on Rails, or Django. We believe that baseline features for creating a web server are pretty much settled and asking someone to configure them manually has no upsides. Features like

Parsing the request body
Validating form data
File uploads
Logging throughout the framework
Cookies + session management
Authentication
SQL ORM
Template engine
Support for sending emails

and much more are already baked into AdonisJS so that you can kick start your projects vs spending time assembling your projects.

Along with the benefits of rapidly developing your apps. There are a few more advantages of using a fully-featured framework like AdonisJS.

The API across all the packages of the framework is consistent and follows similar naming and code conventions. In turn, there is a less cognitive load on you.
Since the framework already knows a lot about your application, it can ship exclusive tooling to further improve your development experience. AdonisJS REPL is a great example of the same.

Closing thoughts

The goal of this post was to mainly introduce you to the framework. Moving forward, we will be writing a lot of code using AdonisJS, Tailwind CSS, and a little bit of AlpineJS.

I will be writing one blog post every day and all you need is to take out 30-45mins and follow along as we create our little todo app. Meanwhile, you can visit the following links to learn more about AdonisJS and show some love ❤️

Twitter: https://twitter.com/adonisframework
Github: https://github.com/adonisjs/core
Website: https://preview.adonisjs.com

Cheers!

DEV Community: Aman Virk

Learn how to generate unique post slugs in Node.js

Creating responsive emails using MJML and AdonisJS

Introducing AdonisJS - Database setup

Prerequisite

Lucid setup

Database Overview

Schema migrations

Creating the categories table

Creating the todos table

Data models

Creating the Category model

Creating the todos model

Setting up the relationship

Demo time

Introducing AdonisJS - Designing the web page

Layouts

Tweaking styles

Components

Dropdown component

Input component

Todo component

Introducing AdonisJS - Setup up Laravel mix

Views & Templates

Rendering views

Creating the view file

Serving static assets

Using assets bundler

Using Laravel Mix

Setup TailwindCSS

Setup Alpine.Js

Closing notes

Introducing AdonisJS - Routes & Controllers

Defining routes

Supported data types

HTTP Context

Using controllers

Lazy loading controllers

Wrap up

Render views

Modify outgoing response

Stream files from the disk

Read request data

Introducing AdonisJS - Part 3

Ace commands

Directory structure

The .adonisrc.json file

The server.ts file

The app directory

The config directory

The start directory

The resources directory

The public directory

The database directory

Typescript first

Fully featured, not full-stack

Introducing AdonisJS - Setup

Prerequisites

Check Node.js version

Creating a new project

Differences between the web and the api project structure

Starting the development server

VSCode setup

What's in the box?

Closing thoughts

Introducing AdonisJS

Outline

Why AdonisJS?

Closing thoughts

Creating the `Category` model

The `.adonisrc.json` file

The `server.ts` file

The `app` directory

The `config` directory

The `start` directory

The `resources` directory

The `public` directory

The `database` directory

Differences between the `web` and the `api` project structure