Adocasts has been a huge part of my life for the past five years, and the people who've subscribed to Adocasts Plus have made it possible to keep the lights on and keep producing content. So, before anything else, thank you! I mean that dearly. You put your trust and faith in me, and I don't take that lightly.

You might remember a post I put up a couple of months back where I said I was taking a break, and went out of my way to say I wasn't quitting. I meant that when I wrote it. The plan was a roughly 90-day reset to recharge and figure out a way forward. The truth is I never actually started that break. Instead, what happened is I unintentionally slowed way down on releasing new Let's Learn AdonisJS 7 lessons, and I ended up spending that quieter stretch weighing my options for the road ahead. That slow drift, more than any clean reset, is really what brought me here. So, as much as it stings to walk back what I said then, here we are.

Let me walk you through what this actually means, why I landed here, and most importantly, how refunds will work for current members.

Why I'm Making This Call

In truth, there isn't one single reason but several reasons that join together. I also can't overstate how much I've teetered on this decision, and I continue to do so to some extent even now.

The biggest piece is time. I've always run Adocasts part-time, alongside a full-time job, and producing long-form content the way I want to takes a lot of hours. As touched on in my last post, I just haven't had the hours or effort to give, and putting out work I'm not proud of isn't something I'm willing to do.

There's also a bigger question hanging over long-form content in general. The way people learn is shifting, and I've spent a long time wondering whether the long, detailed format Adocasts is built on is something I can sustain into the future. I don't have a clear answer here, but it's a real concern and factored in.

The last piece is more personal to where I am in my career. Over the past couple of months, AI has become a much bigger part of how I work, more than I expected when I wrote my last post. This has also shifted my day-to-day role a decent bit. Instead of sitting hands-on in the editor, I'm finding myself directing and managing AI more often than not. It feels a little off to keep teaching from a workflow I've largely moved on from, like I'd be sharing AI's process more than my own.

For a while, I seriously considered pivoting Adocasts toward something more interactive with hands-on learning rather than watching and reading. I still think that's a genuinely exciting direction, and it may be something I come back to one day. However, building something like that properly is an enormous amount of work, and I couldn't see a realistic way to do it side by side while also keeping new Adocasts content flowing. Trying to do both at the same time would mean doing both poorly.

So after circling this decision over and over again, I've concluded that it's time to stop.

The Content Isn't Going Anywhere

Sunsetting Adocasts Plus doesn't mean the content is going to disappear. The whole point of Adocasts was to help people learn AdonisJS, and locking the library away the moment I step back would have undercut the entire reason it existed. So, I'm happy to announce that the entire Adocasts library will be free to all, and this will go into effect here in the next day or two.

There's one piece of unfinished business I do plan to see through, though. I still want to get the Let's Learn AdonisJS 7 series to a proper finished state. I'll be trimming it down from what I currently have planned, but I'd rather land it somewhere that feels complete than leave it hanging. Those lessons will keep coming as a trickle, the same slow pace as anything else from here on, but they will come.

Beyond wrapping that series, you may still see the occasional new lesson pop up from time to time. I'm not committing to a schedule, and I'm not promising anything regular, but if I have something worth sharing, it'll land, free, on Adocasts.

How Refunds Will Work

Since the content everyone paid for is becoming free to all, it didn't sit right with me to keep anyone's money for access that's no longer exclusive. So, all active subscriptions have been canceled, and you won't be charged again. I'm also issuing prorated refunds to Adocasts Plus members, and yes, that includes forever purchasers as well.

The refund is prorated based on how much of your access period you've used: roughly the days you've had access divided by the length of your plan. Monthly and annual members are prorated against their plan length. For forever purchasers, I figured it would be most fair to treat it the same way, refunding the unused portion of your access. I'll be measuring it against a three-year window, since "forever" has no natural end date to calculate against, and three years is what the price was originally based on. To be clear, this isn't me buying back access; the library stays up and free, and you keep everything you always had. It's me returning the slice of a long-term plan that, in fairness, went unused. The math is applied the same way across every tier, so it's as fair and even-handed as I can make it.

A few notes on the mechanics and timing:

• Refunds go back automatically to the original payment method you used. You don't need to do anything or reach out; I'll be processing these one-by-one on my end.

• Most refunds should land within a few business days, though your bank or card issuer can sometimes take a little longer to post it.

• If your original card or account has since been closed, the refund may bounce back to me. If that happens, I'll reach out directly to sort out another way to get it to you.

If something looks off with your refund once it arrives, please get in touch with me via email at tom@adocasts.com, and I'll make it right.

Thank You

Adocasts mattered a lot to me, and the people who supported it mattered more. Watching folks learn AdonisJS through something I built has been one of the most rewarding things I've ever done.

I especially want to thank Harminder Virk and the entire AdonisJS Core Team for being super welcoming and supportive of Adocasts and me. Words can't express how appreciative I am of that. I genuinely think AdonisJS is the option in NodeJS development, and I've been nothing but happy to watch its popularity rise.

The doors to Adocasts aren't locked, the library is free and staying up, and I'm not ruling out a comeback down the road, maybe even in a new format. In the meantime, thank you all very much for being a part of this journey.

Releases

Here's a quick look at what dropped this week:

• @adonisjs/core v7.3.4 — a backward-compatibility fix for the Legacy encryption driver

• @adonisjs/mail v10.3.0 — new Postmark and Cloudflare Email Service transports, plus a few transport fixes

• @adonisjs/i18n v3.0.1 — a fix for confirmed validation rule translation lookups

• edge-markdown v1.10.2 — the same dashCase bug fixed on the Edge side

Native Postmark and Cloudflare Email Transports

The big new feature this week comes from @adonisjs/mail v10.3.0, which ships two new mail transports: Postmark and Cloudflare Email Service.

Postmark is a popular transactional email provider that, up until now, required a workaround to use with AdonisJS. You can wire it up in config/mail.ts like this:

// config/mail.ts
import env from '#start/env'
import { defineConfig, transports } from '@adonisjs/mail'

export default defineConfig({
  default: 'postmark',

  mailers: {
    postmark: transports.postmark({
      key: env.get('POSTMARK_API_KEY'),
      baseUrl: 'https://api.postmarkapp.com/email',
    }),
  },
})

The Cloudflare Email Service transport is also in the codebase, but it's intentionally hidden from defineConfig for now. Cloudflare's service is still in beta, so the team is laying the groundwork ahead of time without surfacing it as a stable option. That's a nice pattern — you'll be able to opt in as soon as it's ready without waiting on the package to catch up.

Encryption Migration Fix in Core

If you've migrated an application from AdonisJS v5 to v6 or v7 and used the Legacy encryption driver to preserve compatibility with old encrypted data, this patch is for you.

The bug was subtle: the Legacy driver was generating initialization vectors (IVs) as raw 16-byte buffers instead of 16-character strings. That mismatch broke decryption of data that was originally encrypted by the old @adonisjs/encryption package. In practice, this means anything stored in your database or sessions that was encrypted under v5 couldn't be decrypted correctly in v7 — which is a pretty significant migration-breaker.

The fix makes the Legacy driver a true drop-in replacement for the old encrypter. If you hit this during a migration and put it on the backburner, now's a good time to revisit it.

make:model Flag Collision Fixed in Lucid

This one's a small but genuinely annoying bug if you've run into it. When using node ace make:model with the -mc flag shorthand, both --transformer and --controller were aliased to -c. That meant running:

node ace make:model -mc Price

would silently generate the model, migration, and transformer — but not the controller. And because -c was claimed by transformer, there was no way to combine --controller with the other flags at all.

The fix is simple: the transformer shorthand moves from -c to -t, so -c reliably means controller again. The updated flag layout looks like this:

# Before: -c was claimed by both transformer and controller
node ace make:model -mc Price        # model + migration + transformer (no controller)

# After: transformer now uses -t, so -c reliably means controller
node ace make:model -mtc Price       # model + migration + transformer + controller

Worth noting: this is technically a breaking change if anything in your scripts was explicitly relying on -c as the transformer shorthand, so keep that in mind when upgrading.

dashCase Bug Fixes in i18n and edge-markdown

Two separate packages got fixes for the same underlying issue this week, which makes it a fun one to explain.

The dashCase utility — which converts things like fieldName into field-name — has a quirk with alphanumeric strings like h2. When passed through dashCase, h2 was being rewritten to h-2, inserting a hyphen between the letter and the number.

i18n: confirmed validation messages

In @adonisjs/i18n, this bug bit the confirmed validation rule. If you had a field named something like h2, the translation lookup would look for the key h-2 instead of h2, and never find a match. Your custom translation strings for that field just wouldn't be picked up.

The fix corrects the transform so original field names resolve to the right translation keys. As a bonus, translateField is now also overridable when extending I18nMessagesProvider, which gives you more flexibility if you're doing anything custom with the messages provider.

edge-markdown: overriding heading components

The same bug showed up in edge-markdown. If you wanted to override how markdown headings render by creating a custom Edge component — say, h2.edge — it simply wouldn't work. The component discovery step was converting h2 to h-2, so your file was never matched to the element.

After the fix, you can define a component like this and it'll be picked up correctly:

// resources/views/components/h2.edge
<h2 class="text-2xl font-bold">
  {{ await $slots.default() }}
</h2>

Super handy if you're using edge-markdown and want consistent heading styles across your app without resorting to global CSS overrides.

Resend and Brevo Transport Fixes

Also bundled into the @adonisjs/mail v10.3.0 release: fixes for the Resend and Brevo transports. Both weren't forwarding custom and list headers on outgoing messages, and there were some edge cases where attachment content wasn't resolving correctly.

If you're using either of those transports, upgrading to v10.3.0 will grab these fixes along with everything else in the release.

New Docs: Protecting Subscription Routes and Testing Broadcasts

The @adonisjs/transmit README got a meaningful update with three previously-missing sections:

• How to protect subscription routes with auth middleware

• A full client-side guide covering beforeSubscribe and Bearer token setup

• A Japa testing section for asserting broadcasts and checking that unauthenticated subscriptions return 401s

If you're using Transmit for server-sent events and felt like the docs were leaving some gaps, this PR fills a lot of them in.

New Docs: Database Assertions for Testing

The v7 docs also got a new section on database assertions — useful for anyone writing Japa tests that need to verify database state after an operation. If that workflow is part of your test suite, it's worth a look.

Supply-Chain Security Hardening

Finally, a coordinated set of security improvements landed across @adonisjs/core, @adonisjs/i18n, and @adonisjs/mail this week. None of it changes runtime behavior, but it's meaningful work:

• npm Trusted Publishing via OIDC

• Pinned GitHub Action SHAs

• npm install --ignore-scripts for dependency installation

• npm audit signatures verification

• Dependabot enabled for GitHub Actions

This kind of infrastructure work is easy to overlook because it's invisible when it's working — but it meaningfully tightens the supply-chain posture of the packages most AdonisJS apps depend on directly. Good to see the team giving it attention.

So, all in all, a solid maintenance week for the ecosystem. The encryption migration fix and the dashCase bugs are probably the most impactful if you've been quietly dealing with either of them, and Postmark support is a welcome addition for anyone on that stack. vinejs, flydrive-js, japa, and Julien-R44's tuyau, hot-hook, and verrou were all quiet this week — so if those are your main dependencies, no action needed.

So, to start, we can delete the route definitions that've been provided to us in our start/routes.ts file. You should just be left with the below after removing.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())

Next, we can remove the new_account_controller, session_controller, and user validator.

rm app/controllers/new_account_controller.ts && 
rm app/controllers/session_controller.ts &&
rm app/validators/user.ts

Perfect! Now all that remains are config-level things that we'll cover as we go through implementing authentication. Then, we've already learned through everything happening in our auth pages, so we can leave those as well and just do a quick refresher.

Starting with our login page.

// resources/views/pages/auth/login.edge
@layout()
  <div class="form-container">
    <div>
      <h1> Login </h1>
      <p>
        Enter your email and password below to log in
      </p>
    </div>

    <div>
      @form({ route: 'session.store', method: 'POST' })
        <div>
          @field.root({ name: 'email' })
            @!field.label({ text: 'Email' })
            @!input.control({ type: 'email' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'password' })
            @!field.label({ text: 'Password' })
            @!input.control({ type: 'password' })
            @!field.error()
          @end
        </div>

        <div>
          @!button({ text: 'Login', type: 'submit' })
        </div>
      @end
    </div>
  </div>
@end

For starters, we have the form component that accepts a method, route, routeParams, and routeOptions to build out the final action URL for the form's submission. This component will also add our CSRF field when performing POST, PUT, PATCH, and DELETE requests.

Then, we have the field components that build out the input fields. The root injects the fields' context, which includes the input's name, old value from the previous submission, and error state. The label, control, and error then use this context to build out their applicable section of the input.

Finally, the button adds a submit button to our form!

Then, the only difference in our signup page is the addition of two fields.

// resources/views/pages/auth/signup.edge
@layout()
  <div class="form-container">
    <div>
      <h1> Signup </h1>
      <p>
        Enter your details below to create your account
      </p>
    </div>

    <div>
      @form({ route: 'new_account.store', method: 'POST' })
        <div>
          @field.root({ name: 'fullName' })
            @!field.label({ text: 'Full name' })
            @!input.control()
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'email' })
            @!field.label({ text: 'Email' })
            @!input.control({ type: 'email', autocomplete: 'email' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'password' })
            @!field.label({ text: 'Password' })
            @!input.control({ type: 'password', autocomplete: 'new-password' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'passwordConfirmation' })
            @!field.label({ text: 'Confirm password' })
            @!input.control({ type: 'password', autocomplete: 'new-password' })
            @!field.error()
          @end
        </div>

        <div>
          @!button({ text: 'Sign up', type: 'submit' })
        </div>
      @end
    </div>
  </div>
@end

The two added fields here are for the user's fullName and then passwordConfirmation to ensure the user knows the password they've entered. An alternative here would be a single password field with a show/hide value toggle.

Lastly, we have in our header partial an if/else for our authentication.

// resource/views/partials/header.edge
<header>
  <div>
    <div>
      @link({ route: 'home', text: 'Home' })
        {{-- svg ... --}}
      @end
    </div>
    <div>
      <nav>
        @if(auth.user)
          @!avatar({ initials: auth.user.initials })
          @form({ route: 'session.destroy', method: 'POST' })
            @!button({ text: 'Logout' })
          @end
        @else
          @!link({ route: 'new_account.create', text: 'Signup' })
          @!link({ route: 'session.create', text: 'Login' })
        @end
      </nav>
    </div>
  </div>
</header>

If the user is logged in and the user has been populated for the request, auth.user will contain the authenticated user. So, when that is truthy, we'll show an avatar with the user's initials and a form to logout.

Note that the logout form sends a POST request. This is done to prevent CSRF attacks. Someone could force users to logout through malicious means if we were to use a GET request. Plus, among other things, it also helps protect against a user accidentally logging out due to pre-fetching. Pre-fetching is when a page is eagerly loaded before the user actually clicks the link.

If the user is not logged in, links to signup or login will be shown. Now, since we've deleted these routes, any pages referencing these routes will now throw a route not found error. Since our header is everywhere, we'll go ahead and just remove this section for now, and we'll add it back as we reimplement things.

// resource/views/partials/header.edge
<header>
  <div>
    <div>
      @link({ route: 'home', text: 'Home' })
        {{-- svg ... --}}
      @end
    </div>
    <div>
      <nav>
++        {{-- TODO --}}
      </nav>
    </div>
  </div>
</header>

Great, let's get started!

The Role of silent_auth_middleware

Before we start gating things, it's worth understanding why auth.user is already available throughout our application, even on pages that don't require authentication, like the home page or the challenges list.

If we open up app/middleware/silent_auth_middleware.ts we'll find:

// app/middleware/silent_auth_middleware.ts
import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class SilentAuthMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    await ctx.auth.check()
    return next()
  }
}

And if we look in start/kernel.ts, this middleware is registered as a router middleware, meaning it runs on every request that hits a registered route.

// start/kernel.ts
router.use([
  () => import('@adonisjs/core/bodyparser_middleware'),
  () => import('@adonisjs/session/session_middleware'),
  () => import('@adonisjs/shield/shield_middleware'),
  () => import('@adonisjs/auth/initialize_auth_middleware'),
  () => import('#middleware/silent_auth_middleware'),
])

The key is that ctx.auth.check() silently attempts to authenticate the user using their session. If a valid session exists, it populates ctx.auth.user with the authenticated user. If not, it does nothing and moves on, no redirect, no error, just continues the request.

That is the key difference between silent_auth_middleware and the named auth middleware we've been working with. The auth middleware also checks authentication, but if the user isn't logged in it stops the request right there and redirects them to the login page. The silent variant just checks and keeps moving.

This is what allows our EdgeJS templates to reference auth.user everywhere, and why our header can conditionally show the avatar or login link without requiring a login. The user's auth state is always resolved by the time a request reaches our controllers or views.

Protecting Challenge Routes

Currently, anyone can access our create, edit, update, and destroy challenge routes whether they're authenticated or not. Let's fix that by adding the auth middleware to those actions on our challenges resource.

The .use() method on a resource accepts the route action names to target as its first argument, and the middleware to apply as its second. We can chain a second .use() call to add our auth middleware alongside our existing request logger.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())
++  .use(['create', 'store', 'edit', 'update', 'destroy'], middleware.auth())

We've left index and show out of the auth group intentionally as anyone should be able to browse the challenges list and view individual challenges. Only creating, editing, and deleting need to be locked down.

Now, if an unauthenticated user tries to visit /challenges/create, the auth middleware will intercept and redirect them to /login instead.

Attaching the Creator

Back in our CRUD Basics lesson, we hit a foreign key constraint when creating challenges because our challenges table requires a creator_id. As a temporary fix, we hardcoded 1 to make things work while we got our data layer in shape. Now that we have authentication in place, let's use the real authenticated user's id.

// app/controllers/challenges_controller.ts

  async store({ request, response, session, auth }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)
++    await Challenge.create({ creatorId: auth.user!.id, ...data })
    session.flash('success', 'Challenge created successfully')
    return response.redirect().toRoute('challenges.index')
  }

Notice the ! after auth.user. TypeScript types auth.user as potentially undefined because it doesn't know which routes have the auth middleware applied. The ! is a non-null assertion, it tells TypeScript "trust me, this will not be undefined here". We can safely make that assertion because our auth middleware guarantees the user is authenticated before this method ever runs.

Verifying Ownership

Requiring authentication gets us partway there, but any logged-in user can still edit or delete any challenge, regardless of who created it. We need to check that the authenticated user is actually the creator before allowing those mutations through.

The pattern is straightforward: find the challenge, compare its creatorId to the authenticated user's id, and redirect with an error flash if they don't match.

Starting with edit:

// app/controllers/challenges_controller.ts

++  async edit({ params, view, auth, response, session }: HttpContext) {
    const challenge = await Challenge.findOrFail(params.id)

++    if (challenge.creatorId !== auth.user!.id) {
++      session.flash('error', 'You do not have permission to edit this challenge')
++      return response.redirect().toRoute('challenges.index')
++    }

    return view.render('pages/challenges/edit', { challenge })
  }

For update, the ownership check comes before the validation. There's no point running our validator if the user doesn't have permission to make this change in the first place. You'll also notice we've moved the Challenge.findOrFail up to the top so we have the record in hand before doing anything else.

// app/controllers/challenges_controller.ts

++  async update({ params, request, response, auth, session }: HttpContext) {
++    const challenge = await Challenge.findOrFail(params.id)

++    if (challenge.creatorId !== auth.user!.id) {
++      session.flash('error', 'You do not have permission to edit this challenge')
++      return response.redirect().toRoute('challenges.index')
++    }

    const data = await request.validateUsing(challengeValidator)
    challenge.merge(data)
    await challenge.save()
    return response.redirect().toRoute('challenges.show', { id: params.id })
  }

And finally, destroy:

// app/controllers/challenges_controller.ts

++  async destroy({ params, response, session, auth }: HttpContext) {
    const challenge = await Challenge.findOrFail(params.id)

++    if (challenge.creatorId !== auth.user!.id) {
++      session.flash('error', 'You do not have permission to delete this challenge')
++      return response.redirect().toRoute('challenges.index')
++    }

    await challenge.related('participants').detach()
    await challenge.delete()
    session.flash('success', `${challenge.text} has been deleted`)
    return response.redirect().toRoute('challenges.index')
  }

Hiding Actions in the Views

Our backend is now protected, but the UI still shows the "Create a new challenge" button to guests and still shows the edit and delete controls to everyone viewing a challenge. Those buttons either lead to a redirect or an access error, so let's clean that up and only show them when they actually apply.

On the challenges index, we only want to show the create button if there's an authenticated user, so we can wrap it in a simple @if check.

// resources/views/pages/challenges/index.edge

++@if (auth.user)
  <a href="{{ route('challenges.create') }}"
    class="button">Create a new challenge</a>
++@endif

On the challenge detail page, the edit and delete actions should only be visible to the challenge's creator. We have auth.user available in the template thanks to silent_auth_middleware, so we can compare challenge.creatorId directly.

// resources/views/pages/challenges/show.edge

++@if (challenge.creatorId === auth.user?.id)
  <a href="{{ editUrl }}" class="button">Edit Challenge</a>
  <button type="submit" form="destroy" class="button destructive">Delete</button>
++@endif

Note that we're using auth.user?.id here rather than auth.user!.id. This page is public, so auth.user may be undefined for guests. The optional chaining means the comparison simply evaluates to false when no one is logged in, which is exactly what we want.

This is a perfectly workable approach for a simple application, but you can imagine it getting repetitive fast. If we add more resources, we'd be writing the same ownership check pattern over and over. That's exactly what AdonisJS's Bouncer package solves: it gives us a centralized, reusable way to define and check authorization rules. We'll cover it in the next module.

node ace make:controller session create store destroy
# DONE:    create app/controllers/session_controller.ts

That'll give us a stubbed controller with three empty methods.

// app/controllers/session_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
  async create({}: HttpContext) {}
  
  async store({}: HttpContext) {}
  
  async destroy({}: HttpContext) {}
  
}

Displaying The Login Form

Starting with the most straightforward, create just needs to render our login page.

// app/controllers/session_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
++  async create({ view }: HttpContext) {
++    return view.render('pages/auth/login')
++  }
  
  async store({}: HttpContext) {}
  
  async destroy({}: HttpContext) {}
  
}

Remember, in the first lesson of this module, we left the pages from the starter kit intact since they didn't include anything we hadn't already discussed. So, that is already good to go.

Authenticating The User

For our store method, we'll start by pulling email and password out of the request body.

// app/controllers/session_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/login')
  }
  
++  async store({ request, auth, response }: HttpContext) {
++    const { email, password } = request.all()
++  }
  
  async destroy({}: HttpContext) {}
  
}

Now, instead of manually looking up the user and comparing passwords ourselves, our User model provides a verifyCredentials static method that handles all of that for us. Under the hood, it finds the user by their email, then uses the hash service to verify that the provided password matches the stored hash.

// app/controllers/session_controller.ts
import User from '#models/user'
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/login')
  }
  
  async store({ request, auth, response }: HttpContext) {
    const { email, password } = request.all()
++    const user = await User.verifyCredentials(email, password)
  }
  
  async destroy({}: HttpContext) {}
  
}

Importantly, if either the email doesn't match a user in our database or the password is incorrect, verifyCredentials will throw an InvalidCredentialsException. This is deliberately vague. Rather than telling the user "no account with that email exists" or "that password is wrong", it simply says the credentials are invalid.

This is a security best practice. If we revealed which part of the credentials was wrong, we'd be confirming which emails have accounts, which an attacker could use to narrow their targets.

AdonisJS's exception handler picks up InvalidCredentialsException and, for HTML form submissions, redirects the user back with a flash message, similar to how validation errors are handled automatically.

If verifyCredentials succeeds, we get back the user's User model instance, and we can log them in exactly as we did after sign up.

// app/controllers/session_controller.ts
import User from '#models/user'
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/login')
  }
  
  async store({ request, auth, response }: HttpContext) {
    const { email, password } = request.all()
    const user = await User.verifyCredentials(email, password)

++    await auth.use('web').login(user)
++    return response.redirect().toRoute('home')
  }
  
  async destroy({}: HttpContext) {}
  
}

Signing Out

Signing out is refreshingly simple. We tell auth to log the user out, then redirect them somewhere. We'll send them back to the login page.

// app/controllers/session_controller.ts
import User from '#models/user'
import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/login')
  }
  
  async store({ request, auth, response }: HttpContext) {
    const { email, password } = request.all()
    const user = await User.verifyCredentials(email, password)

    await auth.use('web').login(user)
    return response.redirect().toRoute('home')
  }
  
++  async destroy({ auth, response }: HttpContext) {
++    await auth.use('web').logout()
++    return response.redirect().toRoute('session.create')
++  }
  
}

Registering Routes & Middleware

With our controller sorted, let's register our routes. We'll also reach for our guest and auth named middleware from start/kernel.ts here, which is where the starter kit has them preconfigured for us.

We want to group the signup and login routes under the guest middleware. The idea is that an already-authenticated user has no business visiting the login or signup pages, so if they try, the middleware redirects them home.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())

++router
++  .group(() => {
    router.get('/signup', [controllers.NewAccount, 'create'])
    router.post('/signup', [controllers.NewAccount, 'store'])

++    router.get('/login', [controllers.Session, 'create'])
++    router.post('/login', [controllers.Session, 'store'])
++  })
++  .use(middleware.guest())

The guest middleware checks whether the user making the request is already authenticated. If they are, it reflashes their existing session data and redirects them to the home page.

Then we add a separate group for the logout route protected by the auth middleware.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())

router
  .group(() => {
    router.get('/signup', [controllers.NewAccount, 'create'])
    router.post('/signup', [controllers.NewAccount, 'store'])

    router.get('/login', [controllers.Session, 'create'])
    router.post('/login', [controllers.Session, 'store'])
  })
  .use(middleware.guest())

++router
++  .group(() => {
++    router.post('/logout', [controllers.Session, 'destroy'])
++  })
++  .use(middleware.auth())

The auth middleware checks that the user is authenticated before letting the request through. If they're not, it redirects them to /login instead. Note that the auth middleware isn't limited to just the logout route; you can wrap any routes you want to protect behind it. For example, if you only want signed-in users to create challenges, which we do, you could add the auth middleware to the create, store, edit, update, and delete endpoints of our challenges resource.

Completing The Header

Last thing! Back in our header, we can now safely fill in that {{-- TODO --}} we left behind two lessons ago. Our session routes are registered, so we won't get any route not found errors.

// resources/views/partials/header.edge
<header>
  <div>
    <div>
      @link({ route: 'home', text: 'Home' })
        {{-- svg ... --}}
      @end
    </div>
    <div>
      <nav>
        @if(auth.user)
          @!avatar({ initials: auth.user.initials })
++          @form({ route: 'session.destroy', method: 'POST' })
++            @!button({ text: 'Logout' })
++          @end
        @else
          @!link({ route: 'new_account.create', text: 'Signup' })
++          @!link({ route: 'session.create', text: 'Login' })
        @end
      </nav>
    </div>
  </div>
</header>

When the user is authenticated, we show their avatar alongside a logout button. The logout is wrapped in a @form that POSTs to session.destroy rather than using a plain link, and that's intentional. Links can be pre-fetched by browsers, meaning a user could be logged out simply because a page eagerly loaded the link in the background. Using a form and a POST request prevents that, and also protects against CSRF-based forced logouts.

When no user is authenticated, we show links to both signup and login.

With that, authentication is fully wired up! Head to /login in your browser, enter the credentials of the account you signed up with, and you should land back on the home page with your initials showing in the header. Hit logout, and you should be sent right back to /login.

Next, we'll require and attach an authenticated user when creating challenges.

node ace make:controller new_account create store
# DONE:    create app/controllers/new_account_controller.ts

Remember, with the make:controller command we can end with a list of methods we want stubbed inside the controller. So, with this we're creating a controller called new_account with two methods, create and store. It'll look like the following to start:

// app/controllers/new_account_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class NewAccountController {
  
  async create({}: HttpContext) {}
  
  async store({}: HttpContext) {}
  
}

We've left our EdgeJS pages intact as we're already familiar with everything going on in those. So, we can get our create out of the way by rendering its page.

// app/controllers/new_account_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class NewAccountController {
  
++  async create({ view }: HttpContext) {
++    return view.render('pages/auth/signup')
++  }
  
  async store({}: HttpContext) {}
  
}

As a reminder, this page includes a form that'll post to new_account.store with the fields fullName, email, password, and passwordConfirmation, as shown below.

// resources/views/pages/auth/signup.edge
@layout()
  <div class="form-container">
    <div>
      <h1> Signup </h1>
      <p>
        Enter your details below to create your account
      </p>
    </div>

    <div>
      @form({ route: 'new_account.store', method: 'POST' })
        <div>
          @field.root({ name: 'fullName' })
            @!field.label({ text: 'Full name' })
            @!input.control()
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'email' })
            @!field.label({ text: 'Email' })
            @!input.control({ type: 'email', autocomplete: 'email' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'password' })
            @!field.label({ text: 'Password' })
            @!input.control({ type: 'password', autocomplete: 'new-password' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'passwordConfirmation' })
            @!field.label({ text: 'Confirm password' })
            @!input.control({ type: 'password', autocomplete: 'new-password' })
            @!field.error()
          @end
        </div>

        <div>
          @!button({ text: 'Sign up', type: 'submit' })
        </div>
      @end
    </div>
  </div>
@end

We'll next want to validate this data so we aren't accepting raw user-provided data. So, let's create our validator next.

node ace make:validator user
# DONE:    create app/validators/user.ts

To start, that'll give us a new user validator file with a single import for VineJS.

// app/validators/user.ts
import vine from '@vinejs/vine'

We'll want to create a new validator in here called signupValidator and export it. Inside, we'll add our form's fields, all of which will be strings.

// app/validators/user.ts
import vine from '@vinejs/vine'

++export const signupValidator = vine.create({
++  fullName: vine.string(),
++  email: vine.string(),
++  password: vine.string(),
++})

Do note, we've omitted the passwordConfirmation field from our validator. We don't actually need that value; all we want to do is ensure it matches one-to-one with the password value. To do that, we can add a confirmed() rule to our password stating it should be confirmed by our passwordConfirmation value.

// app/validators/user.ts
import vine from '@vinejs/vine'

export const signupValidator = vine.create({
  fullName: vine.string(),
  email: vine.string(),
++  password: vine.string().confirmed({
++    confirmationField: 'passwordConfirmation',
++  }),
})

Next, we'll also want to ensure it is at least eight characters long. You can change to match your security policy from there if you'd like. To do this, we could chain it directly to our password rules, but let's mimic what the starter kit had. It had these rules split into their own variable, which opens up the opportunity for reusability for these rules. You might want to reuse this if you have a change password section in your account settings, for example.

// app/validators/user.ts
import vine from '@vinejs/vine'

++const password = () => vine.string().minLength(8).maxLength(32)

export const signupValidator = vine.create({
  fullName: vine.string(),
  email: vine.string(),
++  password: password().confirmed({
    confirmationField: 'passwordConfirmation',
  }),
})

Here we're adding a max length for the password to 32 to match what the starter kit provided, but you can allow this to go longer if you'd like. By default, our database string column length will be 255 characters. Plus, as we discussed in our database module, our User model will secure our password inside our database using a hash and salt mechanism. This results in our password looking like the below inside our database.

$scrypt$n=16384,r=8,p=1$MKExIjg7F/RbrIRl7ZlKPg$Sajr82p4xhTr+0Kw/z6cakM00gh4mDDsil5Ts954pYvuAl7eS2CNLRQzuharYaWnavyx4JrF8EI2zXOxfsnltw

The length of the passwords stored in our database ultimately varies depending on our hash configuration. By default, AdonisJS has set us up with scrypt. We can switch to [argon2](https://docs.adonisjs.com/guides/security/hashing), [bcrypt](https://docs.adonisjs.com/guides/security/hashing), or other solutions via this config if needed. The keyLength` option, omitted from below, is what would add or subtract from the length of the secured password.

// config/hash.ts
import { defineConfig, drivers } from '@adonisjs/core/hash'

/**
 * Hashing configuration.
 * Defines the hashing algorithm and parameters used for password hashing.
 */
const hashConfig = defineConfig({
  /**
   * The default hashing algorithm to use.
   */
  default: 'scrypt',

  /**
   * List of available hashers and their configuration.
   */
  list: {
    /**
     * Scrypt hasher configuration.
     * Scrypt is a password-based key derivation function designed to be
     * computationally intensive and memory-hard to resist brute-force attacks.
     */
    scrypt: drivers.scrypt({
      /**
       * CPU/memory cost parameter.
       * Higher values increase security but require more resources.
       */
      cost: 16384,

      /**
       * Block size parameter.
       * Affects memory usage and performance.
       */
      blockSize: 8,

      /**
       * Parallelization parameter.
       * Controls the number of independent mixing functions.
       */
      parallelization: 1,

      /**
       * Maximum memory in bytes to use for hashing.
       * Set to 32MB (33554432 bytes) by default.
       */
      maxMemory: 33554432,
    }),
  },
})

export default hashConfig

/**
 * Inferring types for the list of hashers you have configured
 * in your application.
 */
declare module '@adonisjs/core/types' {
  export interface HashersList extends InferHashers<typeof hashConfig> {}
}

Several AdonisJS configurations follow this structure. We have a list of configured services, in this case, hashing mechanisms. Then, we specify a default for AdonisJS to use from the list.

Okay, back to our validator. On our users table our email column is marked as unique. We don't want to allow more than one user to use an email; otherwise, that could lead to our accounts cross-pollinating. We can validate this up front to prevent it from failing and erroring out later on when it reaches our database using the unique() rule.

// app/validators/user.ts
import vine from '@vinejs/vine'

++const password = () => vine.string().minLength(8).maxLength(32)

export const signupValidator = vine.create({
  fullName: vine.string(),
++  email: vine.string().unique({ table: 'users', column: 'email' }),
  password: password().confirmed({
    confirmationField: 'passwordConfirmation',
  }),
})

It accepts in options that will help it build out a query. Alternatively, we can also provide a callback function to build the query manually ourselves. Here, we're specifying that we want the user-supplied email value to be unique in our users table's email column. This will perform a quick query to ensure no record with the supplied email exists. If one does exist, we'll get a validation error.

Note, there is also a property on this option set to do a case-insensitive search and another to filter further.

import vine from '@vinejs/vine'

export const exampleValidator = vine.create({
  email: vine.string().unique({ 
    table: 'users', 
    column: 'email',
    caseInsensitive: true,
    filter(db, value) {
      return db.whereNull('deleted_at')
    }
  }),
})

Then, we also need to ensure the value supplied is a valid email structure and that it'll fit in our database column.

// app/validators/user.ts
import vine from '@vinejs/vine'

++const email = () => vine.string().email().maxLength(254)
const password = () => vine.string().minLength(8).maxLength(32)

export const signupValidator = vine.create({
  fullName: vine.string(),
++  email: email().unique({ table: 'users', column: 'email' }),
  password: password().confirmed({
    confirmationField: 'passwordConfirmation',
  }),
})

We'll do something similar to our password and make this reusable, which is handy if you have a change email section in your account settings. Finally, our fullName should be nullable; the user doesn't need to supply it.

// app/validators/user.ts
import vine from '@vinejs/vine'

const email = () => vine.string().email().maxLength(254)
const password = () => vine.string().minLength(8).maxLength(32)

export const signupValidator = vine.create({
++  fullName: vine.string().nullable(),
  email: email().unique({ table: 'users', column: 'email' }),
  password: password().confirmed({
    confirmationField: 'passwordConfirmation',
  }),
})

Jumping back into our NewAccountController, we can validate our request body in our store handler, then use the validated data to create a new user record. We can also redirect our user back home after all is said and done.

// app/controllers/new_account_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class NewAccountController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/signup')
  }
  
++  async store({ request }: HttpContext) {
++    const payload = await request.validateUsing(signupValidator)
++    const user = await User.create(payload)

++    return response.redirect().toRoute('home')
++  }
  
}

In between creating our user and redirecting our user, though, we want to log the user in. We've discussed how auth is a global in our EdgeJS context, but it's also available via our HttpContext as well! It's how we'll login, logout, and otherwise manage our session-based authentication.

// app/controllers/new_account_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class NewAccountController {
  
  async create({ view }: HttpContext) {
    return view.render('pages/auth/signup')
  }
  
++  async store({ request, response, auth }: HttpContext) {
    const payload = await request.validateUsing(signupValidator)
    const user = await User.create(payload)

++    await auth.use('web').login(user)

    return response.redirect().toRoute('home')
  }
  
}

Similar to how hash has a list of configured hashing mechanisms, our auth has a list of configured authentication guards. With the starter kit we've selected, the default guard that's been configured for us is the "web" guard, for session authentication. Here we're using that guard to login the provided user.

If we scope out our auth config to see this guard, we'll find:

// config/auth.ts
import { defineConfig } from '@adonisjs/auth'
import { sessionGuard, sessionUserProvider } from '@adonisjs/auth/session'
import type { InferAuthenticators, InferAuthEvents, Authenticators } from '@adonisjs/auth/types'

/**
 * Authentication configuration.
 * Defines guards and user providers for session-based authentication.
 */
const authConfig = defineConfig({
  /**
   * The default guard to use for authentication.
   * This guard will be used when no specific guard is mentioned.
   */
  default: 'web',

  /**
   * List of authentication guards.
   * Guards define how users are authenticated for different parts of the application.
   */
  guards: {
    /**
     * Web guard uses session-based authentication for web requests.
     */
    web: sessionGuard({
      /**
       * Whether to use "remember me" tokens for persistent authentication.
       * When enabled, users can stay logged in across browser sessions.
       */
      useRememberMeTokens: false,

      /**
       * User provider configuration.
       * Defines how to fetch and verify user credentials.
       */
      provider: sessionUserProvider({
        model: () => import('#models/user'),
      }),
    }),
  },
})

export default authConfig

/**
 * Inferring types from the configured auth
 * guards.
 */
declare module '@adonisjs/auth/types' {
  export interface Authenticators extends InferAuthenticators<typeof authConfig> {}
}
declare module '@adonisjs/core/types' {
  interface EventsList extends InferAuthEvents<Authenticators> {}
}

Note, the web guard is our default guard, and within its configuration is a provider. This provider accepts in our User model, and that is how the login() method we used in our controller knows how to accept a User model instance, among other things.

Great, the last thing to do is register our routes!

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())

++router.get('/signup', [controllers.NewAccount, 'create'])
++router.post('/signup', [controllers.NewAccount, 'store'])

Remember, barrel files are updated when the dev server is running. You may need to boot your dev server to get the NewAccountController added to the controllers.NewAccount barrel mapping.

Finally, back into our header, we can add our sign up link and our authenticated user's avatar.

// resource/views/partials/header.edge
<header>
  <div>
    <div>
      @link({ route: 'home', text: 'Home' })
        {{-- svg ... --}}
      @end
    </div>
    <div>
      <nav>
        @if(auth.user)
          @!avatar({ initials: auth.user.initials })
        @else
          @!link({ route: 'new_account.create', text: 'Signup' })
        @end
      </nav>
    </div>
  </div>
</header>

Here, when a user is authenticated, our auth.user will be populated with the user's User model instance. So, we can use it to show an avatar of their initials. Otherwise, we'll show a link to our sign up page.

That should do it, we should now be able to head into our /signup page in our app and sign up users! Once you sign up, you should be redirected back to the home page, and you should see your user's initials in place of the sign up link.

The following is AI generated based on GitHub activity across the AdonisJS repositories.

Router is Now Macroable

This one is probably the most interesting change of the week. The Router class in adonisjs/http-server now extends Macroable, which means you can add custom methods and getters to it from your own code or from a package — without touching the framework source.

If you've used AdonisJS for a while, you may have run into situations where you wanted to attach a convenience method to the router. Before this change, there was no clean, official way to do that. Now there is.

Here's a quick example of what that looks like in practice:

import router from '@adonisjs/core/services/router'
import { Router } from '@adonisjs/http-server'

Router.macro('apiPrefix', function (this: Router, prefix: string) {
  return this.group(() => {}).prefix(prefix)
})

// Then, anywhere in your routes file:
router.apiPrefix('/api/v1').resource('users', UsersController)

So you're essentially teaching the Router class a new method. Once registered, that method is available on the router singleton just like any built-in method. It's a super clean extension point, and I expect package authors to start taking advantage of this pretty quickly.

This shipped as adonisjs/http-server v9.0.2.

React and Vue ESLint Presets

The @adonisjs/eslint-config package picked up dedicated react and vue presets this week. If you're building an AdonisJS app with Inertia on the frontend, this is going to clean things up nicely.

Previously, if you wanted proper ESLint coverage across your Vue or React files, you had to wire that up yourself alongside the AdonisJS config. Now it's a single option:

// eslint.config.js
import { configApp } from '@adonisjs/eslint-config'
import { vue } from '@adonisjs/eslint-config/vue'

export default configApp(...vue, {
  name: 'inertia-vue ts overrides',
  files: ['inertia/**/*.ts'],
  rules: {
    'vue/component-api-style': 'off',
  },
})

The frontend key tells the config to pull in the appropriate rules for whichever framework you're using. The Inertia block also now automatically covers .vue and .jsx files, so you're not leaving those out of your linting setup by accident.

By the way, the official AdonisJS starter kits have already been updated to use these new presets, so if you scaffold a new project this week you'll get this out of the box.

Bug Fixes

Request Authority Using the Wrong Host Method

In adonisjs/http-server, the request's authority getter wasn't calling the internal host method — it was resolving the host through a different path. Depending on your setup, this could return inconsistent values. The fix is straightforward: authority now delegates to host internally, so you get consistent results either way. This landed in v9.0.1.

PM2 Environment Detection Was Checking the Wrong Variable

In adonisjs/application, the code that detects whether your app is running under PM2 was checking the wrong environment variable. If you're running AdonisJS with PM2, some PM2-specific behavior may not have been triggering correctly as a result. This is fixed in v9.0.1 of the application package.

Starter Kit Cleanup

A few improvements landed in the official starter kits this week that are worth a quick mention.

pnpm v11 install prompts. If you're using pnpm v11 to scaffold a new AdonisJS project, you were getting prompted to manually approve build scripts during install. The starter kits now include pnpm.onlyBuiltDependencies configuration in the generated templates, so that prompt goes away.

Leftover appKey removed from config/app.ts. A stale appKey field was hanging around in the app config template — a leftover that's no longer used in AdonisJS v7. It's been cleaned up. Small thing, but one less "what is this doing here?" moment when you read through a freshly scaffolded project.

Documentation Updates

A couple of doc improvements also landed this week.

The Inertia shared props documentation now includes Vue.js examples alongside the existing React ones. If you're a Vue user following the Inertia docs, you no longer have to mentally translate from React — the Vue version is right there.

There was also a fix to the deepMerge documentation in the Inertia section, where the usage examples were incorrect, and some expanded parameter documentation for several Lucid ORM methods over on the Lucid docs site.

So, all-in-all, a maintenance-heavy week with two features that'll genuinely improve day-to-day ergonomics — especially if you're building Inertia apps or writing packages that need to extend the router. Good steady progress from the team.

Pagination can be a pain to do, but AdonisJS makes it a breeze. We can easily paginate our data using the query builder's paginate() method. It accepts two arguments: the current page of data we're on and the number of results we want per page. The page number starts at one and can increment from there.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .whereHas('createdBy', (creator) =>
        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
      )
      .preload('createdBy')
++      .paginate(1, 12)

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

For example, above, we're grabbing the first page of our challenges, where each page consists of 12 challenges per page. Though the amount we want per page may be static, in most cases, these are fluid numbers often stored in the URL's query string. This allows the user to specify which page of data they're after. It also allows them to specify the number of items they'd like to see per page.

We could grab this off our query string using request.input(), but as we learned several lessons ago, we want to be defensive when accepting data. We also learned that the query string gets merged with our body when passed to the request's validate method. So, we can easily validate our query string data using a validator.

We'll jump into our challenge validation file and add a challengeIndexValidator. If you're going to have a lot of similar paginated pages in your application, you could also just do a paginationValidator if you'd prefer.

// app/validators/challenge.ts
import vine from '@vinejs/vine'

++export const challengeIndexValidator = vine.create({
++  page: vine
++    .number()
++    .parse((value) => value || 1)
++    .positive(),
++  perPage: vine
++    .number()
++    .parse((value) => value || 12)
++    .range([12, 100]),
++})

export const challengeValidator = vine.create({
  text: vine.string().minLength(5).maxLength(255),
  points: vine.number().range([1, 100]),
})

With this, we're stating both page and perPage should be numbers. Our page should be positive (> 0). Then, perPage should be between 12 and 100 to disallow users from requesting something like 10,000 in a page and bog things down. Something new we haven't yet discussed is the parse() method. This is run before any of our validations and allows us to parse and return the input value ourselves. Here, we're using it to set a default value if a page or perPage are omitted. You can find the full list of rules available on vine.number() in the VineJS number type docs.

Then, we can use this validator in our controller and use the validated page and perPage for our pagination.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
++  async index({ request, view }: HttpContext) {
++    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
    const challenges = await Challenge.query()
      .whereHas('createdBy', (creator) =>
        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
      )
      .preload('createdBy')
++      .paginate(page, perPage)

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Now, if we check out our page we'll notice we only see 12 challenges. However, we can update our URL to include a page and/or perPage query string to alter the page we're on and how many items we see per page.

/challenges?page=2&perPage=24

When we call the paginate() method, notice our return type is no longer Challenge[], an array of our Challenge model instances. Rather, it's of type ModelPaginatorContract<Challenge>. The ModelPaginator is a class that extends SimplePaginator that extends Array, meaning it is still iterable, hence why our loop to display the challenges isn't broken. However, it also contains properties and methods to inform and help us work with our paginator. You can find the full paginator API in the Lucid pagination docs.

SimplePaginator {
  // data
  rows: T[]

  // metadata
  perPage: 12,
  currentPage: 1,
  firstPage: 1,
  isEmpty: false,
  total: 37,
  hasTotal: true,
  lastPage: 4,
  hasMorePages: true,
  hasPages: true,

  // methods
  all(), // returns all rows
  getMeta(), // returns JSON metadata
  toJSON(), // return { meta: getMeta(), data: all() }
  queryString(values: { [key: string]: any }), // add qs to generated URLs
  baseUrl(url: string), // set base URL for pagination links
  getUrl(page: number), // returns URL for the page
  getNextPageUrl(), // returns URL for the next page
  getPreviousPageUrl(), // returns URL for the previous page
  getUrlsForRange(start: number, end: number), // returns array of URLs for range
}

So, despite our challenges consisting of only 12 items for our first page of data, we can still get at the overall total with ease via challenges.total.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    @if (session.has('success'))
      <div class="alert alert-success">
        {{ session.get('success') }}
      </div>
    @endif

    <div class="hero">
      <h1>Challenges</h1>
  
      @include('partials/challenge/available_points')

++      <div>
++        Total Challenges: {{ challenges.total }}
++      </div>
  
      <a href="{{ route('challenges.create') }}" class="button">Create a new challenge</a>
    </div>

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
  </div>

@end

Now, we need to allow our users to easily traverse from page to page. Let's start by adding our next and previous links using the getPreviousPageUrl() and getNextPageUrl(). Importantly, note that if there isn't a previous or next page, these will return null, so we'll want to wrap them in an if statement.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    {{-- ... --}}

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
    
++    <div style="display: flex; gap: .25rem;">
++      @if (challenges.currentPage > 1)
++        <a href="{{ challenges.getPreviousPageUrl() }}">Prev</a>
++      @endif
++
++      @if (challenges.hasMorePages)
++        <a href="{{ challenges.getNextPageUrl() }}">Next</a>
++      @endif
++    </div>
  </div>

@end

So, if we're on page one, we won't see our previous link, and if we're on the last page, we won't see our next link. Additionally, if we check out the links generated here, they're pointing to /?page=2, which is our home page. We want this to instead be /challenges?page=2 to keep the user on this page. For that, we can use the baseUrl() method in our controller.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ request, view }: HttpContext) {
    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
    const challenges = await Challenge.query()
      .whereHas('createdBy', (creator) =>
        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
      )
      .preload('createdBy')
      .paginate(page, perPage)

++    challenges.baseUrl(urlFor('challenges.index'))

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Now, all the URLs generated by our paginator will point to /challenges instead of just /. However, if we switch our perPage to 24, for example, notice neither our next nor previous links keep that. We can easily fix that using the queryString() method!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ request, view }: HttpContext) {
    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
    const challenges = await Challenge.query()
      .whereHas('createdBy', (creator) =>
        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
      )
      .preload('createdBy')
      .paginate(page, perPage)

    challenges.baseUrl(urlFor('challenges.index'))
++    challenges.queryString({ page, perPage })

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Despite us adding page to the queryString() method, the URL generation will override it to allow linking to the correct page. If we had additional things we were filtering by, we'd use this same approach to keep those filters in our pagination links.

Now, one more thing while we're in our controller. When paginating, it's always recommended to sort your query. Without a sort, you run the possibility that your results will shuffle from page to page since you're just using your database's inherent sorting. So, let's add a quick sort to ours so we don't run that risk. We can also remove our createdBy filter and preload; we don't actually need them here.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ request, view }: HttpContext) {
    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
    const challenges = await Challenge.query()
++      .orderBy('createdAt', 'desc')
      .paginate(page, perPage)

    challenges.baseUrl(urlFor('challenges.index'))
    challenges.queryString({ page, perPage })

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Similar to firstOrFail(), the paginate() method is a terminating method that stops our ability to chain off the query builder further. So, we'll add our order by before calling paginate. Then, we'll sort by createdAt in desc to order our challenges from newest to oldest.

Jumping back into our challenges.index page, let's add our individual link numbers using the getUrlsForRange() method.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    {{-- ... --}}

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
    
    <div style="display: flex; gap: .25rem;">
      @if (challenges.currentPage > 1)
        <a href="{{ challenges.getPreviousPageUrl() }}">Prev</a>
      @endif

++      @each (anchor in challenges.getUrlsForRange(1, challenges.lastPage))
++        <a href="{{ anchor.url }}">{{ anchor.page }}</a>
++      @endeach

      @if (challenges.hasMorePages)
        <a href="{{ challenges.getNextPageUrl() }}">Next</a>
      @endif
    </div>
  </div>

@end

The getUrlsForRange() method takes in the page range we want to generate URLs for. If we start at 1 and go to the last page, we'll generate the full gamut of URLs needed to get through all our pages of data. This method then returns:

{ url: string; page: number; isActive: boolean }[]

If the generated URL is for the currently displayed page, then isActive will be true. So, we could use this to highlight the active page.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    {{-- ... --}}

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
    
    <div style="display: flex; gap: .25rem;">
      @if (challenges.currentPage > 1)
        <a href="{{ challenges.getPreviousPageUrl() }}">Prev</a>
      @endif

      @each (anchor in challenges.getUrlsForRange(1, challenges.lastPage))
++        <a href="{{ anchor.url }}" style="color: {{ anchor.isActive ? 'blue' : null }}">
          {{ anchor.page }}
        </a>
      @endeach

      @if (challenges.hasMorePages)
        <a href="{{ challenges.getNextPageUrl() }}">Next</a>
      @endif
    </div>
  </div>

@end

Now, whatever page we're actively on will be blue instead of a dark gray.

Okay, last thing. As you go from page to page, notice how our total available points is changing? This is because it's the total available points for the current page of challenges instead of all challenges. Let's query a sum of our total available points to fix this.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ request, view }: HttpContext) {
    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
++    const totalPoints = await Challenge.query().sum('points', 'total').firstOrFail()
    const challenges = await Challenge.query()
      .orderBy('createdAt', 'desc')
      .paginate(page, perPage)

    challenges.baseUrl(urlFor('challenges.index'))
    challenges.queryString({ page, perPage })

++    return view.render('pages/challenges/index', { challenges, totalPoints })
  }

  // ...
}

Here we're using the sum() query builder method to sum all row's points column into a single value. This method also accepts the name/alias as the second argument, so we're calling it total. We're using the model query builder, so our sum will be at totalPoints.$extras.total. If we'd rather just get the value, we can instead use the database query builder.

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'
import { challengeIndexValidator, challengeValidator } from '#validators/challenge'
import type { HttpContext } from '@adonisjs/core/http'
import { urlFor } from '@adonisjs/core/services/url_builder'
++import db from '@adonisjs/lucid/services/db'

export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ request, view }: HttpContext) {
    const { page, perPage } = await request.validateUsing(challengeIndexValidator)
++    const { totalPoints } = await db.from('challenges').sum('points', 'totalPoints').firstOrFail()
    const challenges = await Challenge.query()
      .orderBy('createdAt', 'desc')
      .paginate(page, perPage)

    challenges.baseUrl(urlFor('challenges.index'))
    challenges.queryString({ page, perPage })

++    return view.render('pages/challenges/index', { challenges, totalPoints })
  }

  // ...
}

Remember, this is a lower-level query builder that doesn't go through our models. So, we need to specify tables and columns exactly as they're named in our database. To query from a table, we can use the from(tableName) method. Since this doesn't go through our models, we get back an object representation of what we have queried/selected. Meaning, we can destructure our totalPoints sum directly from our results for use.

Great, all that's left is to swap that into our page! This also removes the need for our template logic to aggregate this, so we can get rid of the partials/challenge/available_points partial we created, as that's no longer needed.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    @if (session.has('success'))
      <div class="alert alert-success">
        {{ session.get('success') }}
      </div>
    @endif

    <div class="hero">
      <h1>Challenges</h1>

++      <div>
++        Total Points Available: {{ totalPoints.toLocaleString() }}
++      </div>

      <div>
        Total Challenges: {{ challenges.total }}
      </div>
  
      <a href="{{ route('challenges.create') }}" class="button">Create a new challenge</a>
    </div>

    {{-- ... --}}
  </div>

@end

Since the sum is a number, we can also format the number (ex, 1,500), using the toLocaleString() method.

They allow us to build these queries using an easy-to-read method chain in TypeScript. Lucid then takes the query we've built, translates it to SQL, executes it, and returns our results to us.

There are two different, high-level, types of query builders:

1. Database query builder (select/insert)

2. Model query builder

The model query builder uses our models as a translation layer between our query and the database. Converting, for example, camel case property usage in our queries to the appropriate snake case column name on our table. They also allow us to use our model relationships as well. Unless otherwise specified, the model query builder will always return an instance of the model as well.

The database query builder is a more raw query builder that doesn't integrate with our models at all. Instead, it goes directly to the database. It also requires manual typing if you wish for it to have a type other than any.

Building Queries

Let's start simple by replacing the Challenges.all() query from our ChallengesController.index method to instead use our Challenge model's query builder. To start a query builder, all we need to do is call the query() method on our model.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
++    const list = await Challenge.query()
    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

What we've just done is a one-for-one swap, as both Challenge.all() and Challenge.query() will return all records in our challenges table. However, unlike all(), we can chain additional methods off of query() to alter our results.

For example, if we wanted to limit our challenges to those with a point value higher than 50, we could add a where() method. This, in turn, adds a WHERE clause to the SQL our builder will generate and execute.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
++    const list = await Challenge.query().where('points', '>', 50)
    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

The first argument is the column/property name, the second argument is the comparison operator, and the third is the comparison value. This will add a WHERE points > 50 clause to the underlying SQL that'll be executed, limiting the returned challenges that we can see reflected on our page. We can also sort our results as well! Let's sort our challenges by their text.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
++    const list = await Challenge.query().where('points', '>', 50).orderBy('text')
    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

The default sort direction will be ascending (A-Z). We can switch this to descending (Z-A) if we prefer, though.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
++    const list = await Challenge.query().where('points', '>', 50).orderBy('text', 'desc')
    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

Let's filter a little more, by adding an additional where() method to our query, we're saying to get challenges where the points are greater than 50, and the text is whatever the first item on our page is, like "input solid-state feed."

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
++      .where('text', 'input solid-state feed')
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

With the where() method, when we only provide two arguments, column and value, an equality check will be performed by default. Note, similar to the findBy() method, this can also be an object with key/value pairs if all you need are equality checks.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
++      .where({ text: 'input solid-state feed' })
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

If we need a likeness check, we can pass LIKE or ILIKE as the comparison operator and add the percent sign (%) as needed to our value.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
++      .where('text', 'LIKE', 'input%')
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

This will give us all challenges where the points are greater than 50, and the text starts with "input", for example. So far, we've been doing AND WHERE statements, but what if we need OR WHERE? Well, there's an orWhere() method just for that, and it works just like where(), changing just the comparison type.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
++      .orWhere('text', 'LIKE', 'input%')
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

So, this will now give us challenges with points greater than 50 or text starting with input. By the way, if you prefer the explicitness of the orWhere() and would prefer to have that with and comparisons, there is also an andWhere() you can use as an alternative.

Okay, what about mixing and/or statements? For this, the where() methods can also accept a callback function that is provided a nested version of the query builder. This nested version will be translated to SQL wrapped in parentheses, allowing us to build more complex where clauses.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
++      .where((query) => query
++        .where('text', 'LIKE', 'input%')
++        .orWhere('text', 'LIKE', 'index%')
++      )
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

Now, we'll get challenges with points greater than 50 and having a text value starting with input or index. In turn, generating SQL like:

SELECT
  *
FROM
  challenges
WHERE
    points > 50
AND (
     text LIKE 'input%'
  OR text LIKE 'index%'
)

We aren't using the createdAt nor updatedAt at the moment, so if we wanted to save a little, we could omit those columns from our query using the select() method.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
      .where((query) => query
        .where('text', 'LIKE', 'input%')
        .orWhere('text', 'LIKE', 'index%')
      )
++      .select('id', 'text', 'points')
      .orderBy('text', 'desc')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

This will still return an instance of our model, but will now only have the id, text, and points properties populated. Also, unlike SQL, note that it doesn't matter what order we add our query methods in. In SQL, the SELECT comes first, but we can put that after our where clauses as we have above with the query builder. It won't impact the SQL it ultimately generates.

If we need to sort by more than one column, we can do that as well by passing an array into the orderBy() method. All we need to do is specify the column and order for each item we'd like to sort by. It'll then sort in the order of the items in our array.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
      .where((query) => query
        .where('text', 'LIKE', 'input%')
        .orWhere('text', 'LIKE', 'index%')
      )
      .select('id', 'text', 'points')
++      .orderBy([
++        { column: 'text', order: 'desc' },
++        { column: 'points', order: 'asc' },
++      ])

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

This will now sort by our text in descending order, then by our points in ascending order.

Joins

Joins allow us to include another table's records in our query via our relationship columns. Note, these are not the model relationships we'll be discussing in the next lesson, but rather a direct query statement being added into our generated SQL. In most cases, model relationships will eliminate the need to use joins altogether.

To add a join, we can use the join() method. This accepts the table we want to join, followed by the columns we want to compare to match the relationship rows. For example, in a join, we want to map challenges.creator_id to users.id. Joins are lower-level and aren't model away, so we do need to use the column names from our table. Once joined, we can use columns as needed from the joined table.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
      .where((query) => query
        .where('text', 'LIKE', 'input%')
        .orWhere('text', 'LIKE', 'index%')
      )
++      .join('users', 'users.id', 'challenges.creator_id')
++      .select('challenges.id', 'text', 'points', 'users.full_name')
++      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

Here we're joining our users table with our challenges table using a comparison between the users.id and the challenges.creator_id. We're selecting and ordering by the creator's full_name from our users table. I've prefixed full_name with users.full_name, not because it needs to be, but rather because it makes it clear that the column is coming from a join. It'll make it easier to know the column needs to be removed if the join is ever removed.

I am, however, prefixing our select's id with challenges.id for a very specific reason. Both our users and challenges table have an id column. Since both id columns are now present within our query, we need to be explicit about which we're referencing. Without it, we'd get an ambiguous error as SQL wouldn't know whether to use challenges.id or users.id.

Despite our joining in our users table and selecting the users.full_name column, we will still get back instances of our Challenge model for our result. Lucid will populate the Challenge model's columns as usual, and put anything extra from the query that's been selected into an $extras object.

So, if we were to console log the $extras from each of our models, we'd see the creator name for each of our challenges!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const list = await Challenge.query()
      .where('points', '>', 50)
      .where((query) => query
        .where('text', 'LIKE', 'input%')
        .orWhere('text', 'LIKE', 'index%')
      )
      .join('users', 'users.id', 'challenges.creator_id')
      .select('challenges.id', 'text', 'points', 'users.full_name')
      .orderBy('users.full_name')

++    console.log({ extras: list.map((item) => item.$extras) })

    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

If you want to include the creator on each challenge or filter by the creator, we'll see a much cleaner way to do that using model relationships in the next lesson.

Limiting Results

What if we're after a specific number of records? For example, in our ChallengesController.show method, we only want one result, so how could we do that using the query builder? First, let's replace our Challenge.findBy() with our query builder.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.query().where('id', params.id)
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Then, for starters, to restrict the number of results, we can use the query builder's limit() method. This takes in the number of records we want to get back, and it will query for the first X amount up to our limit. So, to get just one, we could use limit(1).

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.query().where('id', params.id).limit(1)
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

However, limit() will still return an array. If we're after just one result, we have better options, like the first() method. This will apply a limit of one and give us our model instance back directly, instead of it being wrapped in an array!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.query().where('id', params.id).first()
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Similar to our static model method, there is also firstOrFail(). This will attempt to find the first result, and if it can't, will throw a 404 Not Found exception. This is more appropriate for our ChallengesController.show as if a challenge can't be found, then there's nothing to show.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.query().where('id', params.id).firstOrFail()
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Building with the Builder

Finally, we don't need to directly chain methods consecutively with the query builder. In fact, the query won't actually execute as SQL until it is awaited or we call a terminating method, like firstOrFail(). This gives us the ability to systematically build on the query as needed. A simple example, but the following gives you a sense of what I mean.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    // start a query builder
++    const query = Challenge.query()

    // add statements as needed
++    query.where('id', params.id)
    
    // firstOrFail is terminating, meaning we can't chain further on it
    // it'll return Promise<Challenge>
++    const challenge = await query.firstOrFail() 

    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Let's move to our index method for a more detailed look.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    // start a query builder
    const query = Challenge.query()

    // add or chain statements as needed
    query.where('points', '>', 50)
    query.where((q) => q.where('text', 'LIKE', 'input%').orWhere('text', 'LIKE', 'index%'))
    query.join('users', 'users.id', 'challenges.creator_id')
    query.select('challenges.id', 'text', 'points', 'users.full_name')
    query.orderBy('users.full_name')

    // await the query to execute
    const challenges = await query

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Here we're getting the query builder and adding our statements to it individually, one at a time. Though these statements return back our query builder, we don't need to overwrite query, they'll be internally applied to the query we're building. Finally, we aren't using any terminating statements, so the query is translated to SQL and executed only when we await the query.

Okay - I'm going to undo all of that to get us back to where we were.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .where('points', '>', 50)
      .where((query) => query
        .where('text', 'LIKE', 'input%')
        .orWhere('text', 'LIKE', 'index%')
      )
      .join('users', 'users.id', 'challenges.creator_id')
      .select('challenges.id', 'text', 'points', 'users.full_name')
      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    const challenge = await Challenge.query().where('id', params.id).firstOrFail()
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Eagerly Loading Relationships

To start, on our challenges.show page, we may want to show the details of the person who created the challenge. To do this using our Challenge model's relationship to the creator, we can eagerly load the relationship onto the queried results using the preload() method from our query builder.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    const challenge = await Challenge.query()
++      .preload('createdBy')
      .where('id', params.id)
      .firstOrFail()
      
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

With model relationships, the entire relationship we've loaded is populated into its own model via the relationship property. For example, by preloading the createdBy relationship, we can now access the creator's User model instance via challenge.createdBy directly from our query's result.

Furthermore, the loaded relationship gets its own query builder as well, which we can access via the second argument. So, if we wanted to just select the firstName and id, we can do that!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    const challenge = await Challenge.query()
++      .preload('createdBy', (query) => query.select('id', 'fullName'))
      .where('id', params.id)
      .firstOrFail()
      
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

This type of relationship loading, using preload() is called eager-loading because the relationships are immediately requested. They're also requested in a manner that minimizes the number of queries needed and accounts for the N+1 problem.

For example, if you have 50 challenges and want to load the creator for each, the N+1 problem would be fetching the challenges, then looping over them to query their creators, one by one, using a separate query for each, for a total of 51 queries. An easy bottleneck in any application. Eager-loading solves this by instead using just 2 queries by:

1. Querying for the challenges

2. Grabbing all the challenge's creatorIds

3. Fetching all the creators in a single query

4. Populating the related creator into each challenge

Lazily Loading Relationships

Though preload() can be more efficient with lists of data, there's no real benefit when working with singular records, like we are in our show and edit handlers. In these situations, we may choose to lazily-load the relationship by loading it at a point dissociated with the original query. This comes in particularly handy with our static model query methods, like findOrFail(), because it gives us a way to populate a relationship for these queries using the load() method.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
    const challenge = await Challenge.findOrFail(params.id)

++    await challenge.load('createdBy')

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  // ...
}

The load() method works just like preload(), the only difference being how the relationship is loaded; preload() is for eager-loading and load() is for lazy-loading.

Counts & Aggregates

We can also use dedicated methods to load relationship counts and aggregates as well. When lazy-loading, the methods to do so are loadCount() and loadAggregate(). For example, if we want to include the number of participants for a challenge, we can use loadCount('participants').

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
    const challenge = await Challenge.findOrFail(params.id)

    await challenge.load('createdBy')
++    await challenge.loadCount('participants')

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  // ...
}

There aren't dedicated columns for counts nor aggregates, so again, these will be populated onto the $extras object of our returned model instance. They're also given a default name from a snake case concatenation of the relationship property name and count, for example, our participant count will be participants_count and can be accessed via challenge.$extras.participants_count.

We can also give it a name of our own, for example, let's say we ultimately want three counts:

1. Total number of participants

2. Total number of participants who have not completed the challenge

3. Total number of participants who have completed the challenge

To start, we'll add two additional counts and filter them by the pivot table's completed_at column. To do this, there are several special purposed wherePivot() methods to filter a many-to-many relationship by their pivot table data. For this particular check, we'll use whereNullPivot() and whereNotNullPivot().

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
    const challenge = await Challenge.findOrFail(params.id)

    await challenge.load('createdBy')
    await challenge.loadCount('participants')
++    await challenge.loadCount('participants', (query) => query.whereNullPivot('completed_at'))
++    await challenge.loadCount('participants', (query) => query.whereNotNullPivot('completed_at'))

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  // ...
}

Next, we can give them applicable names via their callback query builders by adding an as() method to manually give them a name applicable to their purpose.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
    const challenge = await Challenge.findOrFail(params.id)

    await challenge.load('createdBy')
    await challenge.loadCount('participants')

++    await challenge.loadCount('participants', (query) => 
++      query.whereNullPivot('completed_at').as('not_completed_count')
++    )

++    await challenge.loadCount('participants', (query) => 
++      query.whereNotNullPivot('completed_at').as('completed_count')
++    )

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  // ...
}

With this, we'll now get three separate counts for our challenges!

1. participants_count - the total number

2. not_completed_count - the total number who haven't completed the challenge

3. completed_count - the total number who have completed the challenge

We probably don't need these counts on our edit page, though, so let's instead do this same thing using our query builder on our show handler! Instead of loadCount() all we need to do is use withCount() instead, everything else remains the same!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    const challenge = await Challenge.query()
      .preload('createdBy', (query) => query.select('id', 'fullName'))
++      .withCount('participants')
++      .withCount('participants', (query) =>
++        query.whereNullPivot('completed_at').as('not_completed_count')
++      )
++      .withCount('participants', (query) =>
++        query.whereNotNullPivot('completed_at').as('completed_count')
++      )
      .where('id', params.id)
      .firstOrFail()
      
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Now, when using the aggregate version of these methods, like withAggregate() it's on us to perform the type of aggregation we're after within the callback query builder. This gives us a fluid way to build counts, averages, min, max, and other aggregates as needed. For example, let's replace our withCount('participants') with an aggregate usage.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
    const challenge = await Challenge.query()
      .preload('createdBy', (query) => query.select('id', 'fullName'))
++      .withAggregate('participants', (query) => query.count('*').as('participants_count'))
      .withCount('participants', (query) =>
        query.whereNullPivot('completed_at').as('not_completed_count')
      )
      .withCount('participants', (query) =>
        query.whereNotNullPivot('completed_at').as('completed_count')
      )
      .where('id', params.id)
      .firstOrFail()
      
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Here we're not filtering at all, though we could. Then, we're counting the result of all columns using *. Finally, aggregates must be given a name, so we're manually setting it to participants_count.

Any of these can be freely used on our show page, so let's add the challenge's creator and participants.

// resources/views/pages/challenges/show.edge
@layout()

  <div class="hero">
    <h1>{{ challenge.text }}</h1>
    <p>Points: {{ challenge.points }}</p>
++    <p>Created by: {{ challenge.createdBy.fullName }}</p>
++    <p>Participants: {{ challenge.$extras.participants_count }} ({{ challenge.$extras.completed_count }} completed)</p>

    <a href="{{ editUrl }}" class="button">Edit Challenge</a>
    <button type="submit" form="destroy" class="button destructive">Delete</button>
  </div>

  @!form({ id: 'destroy', route: 'challenges.destroy', routeParams: { id: challenge.id }, method: 'DELETE' })

@end

We didn't add any completed participants in our seeder, so it'll be all 0's across the board there for the moment.

Eager Loading & Joining

Let's return to our index handler where we have our join. We now know that we can alternatively eager-load the relationship instead of joining. Meaning, if we do that, we can remove our users.full_name from the select list.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .where('points', '>', 50)
      .where((q) => q.where('text', 'LIKE', 'input%').orWhere('text', 'LIKE', 'index%'))
++      .preload('createdBy')
++      .select('challenges.id', 'text', 'points')
      .join('users', 'users.id', 'challenges.creator_id')
      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

However, since model relationships are queried for and populated post-query, they require the relationship's foreign key to be included within the select list. Otherwise, Lucid won't be able to populate the relationship. Without it, we'll see an exception like:

Cannot preload "createdBy", value of "Challenge.creatorId" is undefined. Make sure to set "null" as the default value for foreign keys

This can be easily solved by adding the creatorId into our select list of our query builder!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .where('points', '>', 50)
      .where((q) => q.where('text', 'LIKE', 'input%').orWhere('text', 'LIKE', 'index%'))
++      .preload('createdBy')
++      .select('challenges.id', 'text', 'points', 'creatorId')
      .join('users', 'users.id', 'challenges.creator_id')
      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Also note, we're still joining here, which allows us to order by the joined relationship. This is one thing we can't do directly with model relationships, and are where using joins comes in handy. Since we are still joining, we still have the ambiguous id column and still need to reference challenges.id specifically in our select list. However, do note, if we omit our select list, Lucid will be able to handle the ambiguity on its own without issue!

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .where('points', '>', 50)
      .where((q) => q.where('text', 'LIKE', 'input%').orWhere('text', 'LIKE', 'index%'))
      .preload('createdBy')
      .join('users', 'users.id', 'challenges.creator_id')
      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

Filtering By Relationships

Finally, if we need to filter our results by the relationship at all with the query builder, we can do that with ease using specialized where methods for relationships. For example, if we only want to include challenges from creators with a public profile, we could do something like:

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .where('points', '>', 50)
      .where((q) => q.where('text', 'LIKE', 'input%').orWhere('text', 'LIKE', 'index%'))
++      .whereHas('createdBy', (creator) =>
++        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
++      )
      .preload('createdBy')
      .join('users', 'users.id', 'challenges.creator_id')
      .orderBy('users.full_name')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

This will limit our challenges to those where challenge.createdBy.profile.isPublic is true! Let's simplify this query so we can see exactly what the whereHas() and preload() methods are executed via the SQL that's executed! By the way, for any of these, you can find the executed SQL printed out in your terminal for convenience.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    const challenges = await Challenge.query()
      .whereHas('createdBy', (creator) =>
        creator.whereHas('profile', (profile) => profile.where('isPublic', true))
      )
      .preload('createdBy')

    return view.render('pages/challenges/index', { challenges })
  }

  // ...
}

First, we have the main query from our query builder with the relationship filtering via whereHas(). The SQL generated for this is:

SELECT
  *
FROM
  `challenges`
WHERE
  EXISTS (
    SELECT
      *
    FROM
      `users`
    WHERE
      (
        EXISTS (
          SELECT
            *
          FROM
            `profiles`
          WHERE
            (`is_public` = ?)
            AND (`users`.`id` = `profiles`.`user_id`)
        )
      )
      AND (`users`.`id` = `challenges`.`creator_id`)
  ) [ true ]

As you can see whereHas() directly filters the query using an EXISTS predicate! We can also see our where clause uses SQL parameterization to help protect us against injection attacks.

Then, we have the query run for our preload(). The SQL generated for this is:

SELECT * FROM `users` WHERE `id` IN (?, ?, ?, ?, ?, ?, ?) [
  8, 1, 7, 3,
  6, 10, 9
]

So, amongst our challenges being queried, we have seven distinct creators. Lucid queries these separately, then fills them into the challenge.createdBy property post-query to keep things efficient and again to solve the N+1 problem.

Seeders allow us to populate our database with preliminary data. We might need preliminary data for a few different reasons, like:

• Default data required by an application, like our roles

• Development environments, to get teammates up and running as quickly as possible

• Resetting a demo environment to showcase our project to prospective clients

We can use the Ace CLI's make:seeder command to easily add a seeder to our application. Let's make one called default we can use it for our roles.

node ace make:seeder default
# DONE:    create database/seeders/default_seeder.ts

Seeders can be found within the database/seeders/ directory, and our new DefaultSeeder will look like below.

import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  async run() {
    // Write your database queries inside the run method
  }
}

Exactly as the comment states, all we need to do is create our preliminary data within the run() method. That run() method will then be run when our seeder is called. So, for our roles, we can create a user and an admin role.

// app/seeders/default_seeder.ts
import { BaseSeeder } from '@adonisjs/lucid/seeders'
++import Role from '#models/role'

export default class extends BaseSeeder {
  async run() {
    // Write your database queries inside the run method
++    await Role.createMany([{ name: 'User' }, { name: 'Admin' }])
  }
}

In the vast majority of cases, you'll want to let your database set your records' IDs. However, for our roles, we have 1 hard-coded as the default role_id in our create_users_table migration. So, it would be great to force our role's ID in our seeder so we know for a fact we have a user role with an ID of 1 and an admin role with an ID of 2. We don't want to allow an ID of 1 to have a possibility of becoming a super user or anything of the sort.

// app/seeders/default_seeder.ts
import Role from '#models/role'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  async run() {
    // Write your database queries inside the run method
++    await Role.createMany([
++      { id: 1, name: 'User' },
++      { id: 2, name: 'Admin' },
++    ])
  }
}

We can take this a step further and give ourselves an enum-like const representation of these values to use throughout our application as well.

touch app/enums/roles.ts

// app/enums/roles.ts
export const Roles = {
  USER: 1,
  ADMIN: 2,
} as const

Then, we can use that in place of hard-coded numbers so they're easier to read!

// app/seeders/default_seeder.ts
import Role from '#models/role'
import { BaseSeeder } from '@adonisjs/lucid/seeders'
import { Roles } from '../../app/enums/roles.ts'

export default class extends BaseSeeder {
  async run() {
    // Write your database queries inside the run method
    await Role.createMany([
++      { id: Roles.USER, name: 'User' },
++      { id: Roles.ADMIN, name: 'Admin' },
    ])
  }
}

Note that the import here is a relative import. If you prefer a subpath import, as our models use, we can add one to our package.json for our new enums directory.

// package.json
{
  ".": "...",
  "imports": {
    "#controllers/*": "./app/controllers/*.js",
++    "#enums/*": "./app/enums/*.js",
    "#exceptions/*": "./app/exceptions/*.js",
    "#models/*": "./app/models/*.js",
    "#mails/*": "./app/mails/*.js",
    "#services/*": "./app/services/*.js",
    "#listeners/*": "./app/listeners/*.js",
    "#generated/*": "./.adonisjs/server/*.js",
    "#events/*": "./app/events/*.js",
    "#middleware/*": "./app/middleware/*.js",
    "#validators/*": "./app/validators/*.js",
    "#providers/*": "./providers/*.js",
    "#policies/*": "./app/policies/*.js",
    "#abilities/*": "./app/abilities/*.js",
    "#database/*": "./database/*.js",
    "#tests/*": "./tests/*.js",
    "#start/*": "./start/*.js",
    "#config/*": "./config/*.js"
  },
  ".": "...",
}

We can then switch our role import to be from #enums/roles.

// app/seeders/default_seeder.ts
import Role from '#models/role'
import { BaseSeeder } from '@adonisjs/lucid/seeders'
++import { Roles } from '#enums/roles'

export default class extends BaseSeeder {
  async run() {
    // Write your database queries inside the run method
    await Role.createMany([
++      { id: Roles.USER, name: 'User' },
++      { id: Roles.ADMIN, name: 'Admin' },
    ])
  }
}

Again, we can also update our migration; the value will remain the same, so no need to refresh or re-run the migration for this change.

// database/migrations/xxxxx_create_users_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'
++import { Roles } from '#enums/roles'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable()
      table
        .integer('role_id')
        .unsigned()
        .references('id')
        .inTable('roles')
        .notNullable()
++        .defaultTo(Roles.USER)
      table.string('full_name').nullable()
      table.string('email', 254).notNullable().unique()
      table.string('password').notNullable()

      table.timestamp('created_at').notNullable()
      table.timestamp('updated_at').nullable()
    })
  }

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

Running Seeders

We can run seeders using the db:seed Ace CLI command. This will run all seeders defined in our application, though we can specify a specific file or files using the --files option or its alias -f. There's also an interactive mode we can use with --interactive or its alias -i. The interactive mode will allow us to select specifically which seeders we'd like to run from a list of our seeders.

node ace db:seed

However, if we were to try to run our seeder at the moment, we would get a unique constraint.

node ace db:seed
#❯ error     database/seeders/default_seeder
#  insert into `roles` (`created_at`, `id`, `name`, `updated_at`) values ('2026-02-06 01:00:50', 1, 'User', '2026-02-06 01:00:50') - UNIQUE constraint failed: roles.id

Remember, we've already created a role with an ID of 1 in the last lesson using REPL, so the unique constraint is complaining that the ID of 1 we're trying to insert already exists. So, let's wipe our database's data first!

node ace migration:fresh

This will drop all our tables and rerun all our migrations. Then, we can retry our seeder.

node ace db:seed
# "sqlite" Role (2.27 ms) INSERT INTO `roles` (`created_at`, `id`, `name`, `updated_at`) VALUES (?, ?, ?, ?) [ '2026-02-06 01:07:31', 1, 'User', '2026-02-06 01:07:31' ]
# "sqlite" Role (56 μs) INSERT INTO `roles` (`created_at`, `id`, `name`, `updated_at`) VALUES (?, ?, ?, ?) [ '2026-02-06 01:07:31', 2, 'Admin', '2026-02-06 01:07:31' ]
# ❯ completed database/seeders/default_seeder

By the way, we could've done all of that in a single command with:

node ace migration:fresh --seed
# or
node ace migration:refresh --seed

This would've run migration:fresh or migration:refresh and all our seeders in a single command.

Environment Specific Seeders

Our default seeder, creating our roles, we want to run in any environment because every environment needs our roles to exist. However, if we're creating dummy data for our development environment, we don't want to run the risk of accidentally running that in production. To avoid that, we can gate it to specific environments.

To start, let's make a dev seeder.

node ace make:seeder dev

Then, to gate it so it will only run in development, we can add a static environment property on the class. This accepts a string array of the environments we want this seeder to be allowed to run within. So, by adding "development" to this array, we're limiting the seeder so it can only run in our development environment.

// database/seeders/dev_seeder.ts
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
++  static environment: string[] = ['development']

  async run() {
    // Write your database queries inside the run method
  }
}

Now, we don't want to have to create a bunch of dummy data for development by hand, as we did with our roles. To fix that, we can use factories.

Factories

Factories are wrappers around our models to aid in creating real database records with fake data. This can be handled in two scenarios.

1. Quickly seeding development data without manual data entry.

2. Aide with testing, allowing us to create data with breeze on a per-test basis.

We can easily create factories using the Ace CLI's make:factory command, or by providing the -f flag when using the make:model command. We've already created our models, so let's use make:factory, starting with our challenge.

node ace make:factory challenge
# DONE:    create database/factories/challenge_factory.ts

We can find our factories within the database/factories/ directory, and our new RoleFactory will look like below.

// database/factories/challenge_factory.ts
import factory from '@adonisjs/lucid/factories'
import Challenge from '#models/challenge'

export const ChallengeFactory = factory
  .define(Challenge, async ({ faker }) => {
    return {}
  })
  .build()

Factories are defined by passing it our model's class, Challenge, as the first argument. Then, in the second argument, we use a callback function to return a representation of how that model's data should be filled with fake data. To do this, we'll use faker which is being destructured from the FactoryContext.

Despite our challenges table containing the following columns:

• id

• creator_id

• text

• points

• created_at

• updated_at

We only need to worry about specifying our our text and points columns should be populated with fake data. Our database will automatically handle id. AdonisJS will automatically handle our created_at and updated_at thanks to the options provided to the @column.dateTime() decorator on the column's model representation. Then, creator_id relates a challenge to a user and has a foreign key constraint. So, we'd be better off deferring that to a relationship, as we'll see in a bit.

Defining Factory Properties

So, to start, we can add a text property to the object being returned by our factory's callback method. Then, we can use faker to describe what sort of fake value should be used to populate text. Using the model passed into the first argument, Lucid will also provide us with type safety here and autocomplete for our model's properties.

// database/factories/challenge_factory.ts
import Challenge from '#models/challenge'
import factory from '@adonisjs/lucid/factories'

export const ChallengeFactory = factory
  .define(Challenge, async ({ faker }) => {
    return {
++      text: faker.git.commitMessage(),
    }
  })
  .build()

The faker object contains several category-based properties, and each category contains another object with methods inside it. We'll call one of those methods to describe the type of value that should be used for our property. Within faker there isn't a great option that suits a "challenge", but we can use a like-value we should be familiar with by utilizing faker.git.commitMessage() to assign our text a fake commit message, like "reboot cross-platform driver."

Next, we can do the same for our points, describing it should be an integer number. Some of these faker methods accept options, like the int() method. We can use it to keep the fake value within a min and max range matching that of our validation, 1 and 100.

// database/factories/challenge_factory.ts
import Challenge from '#models/challenge'
import factory from '@adonisjs/lucid/factories'

export const ChallengeFactory = factory
  .define(Challenge, async ({ faker }) => {
    return {
      text: faker.git.commitMessage(),
++      points: faker.number.int({ min: 1, max: 100 }),
    }
  })
  .build()

Fantastic! Before we can add relationships to our factory, we must first have a factory representation of the related model. So, let's go ahead and create our other two factories. Again, similar to our model the challenge_user table is a pivot table and can be sufficiently represented by a relationship between our Challenge and User model. Then, we won't be making a factory for our Role model because those are usually static within an application and won't need to use fake data.

node ace make:factory profile
# DONE:    create database/factories/profile_factory.ts

node ace make:factory user
# DONE:    create database/factories/user_factory.ts

For our ProfileFactory, we just need to specify how to populate our bio and is_public columns. Within the person category there is a one-to-one match for our bio. Then, in datatype there is a one-to-one match for a boolean value for our is_public flag.

// database/factories/profile_factory.ts
import Profile from '#models/profile'
import factory from '@adonisjs/lucid/factories'

export const ProfileFactory = factory
  .define(Profile, async ({ faker }) => {
    return {
      bio: faker.person.bio(),
      isPublic: faker.datatype.boolean(),
    }
  })
  .build()

Finally, we have our UserFactory. Like we did in our migration, we can hard-code the roleId to just 1 which will represent our basic "user" role. Then we have one-to-one matches for our fullName and email columns. For our password, we could use faker.internet.password(). However, our User model will hash the password before saving it into the database. Meaning, if we wanted to login as any of these fake users, we'd need to reset their password. Since we're in development and using a database on our local machine, we can save ourselves the hassle and hard-code the password to something so we know everyone's password on our local database.

// database/factories/user_factory.ts
import User from '#models/user'
import factory from '@adonisjs/lucid/factories'

export const UserFactory = factory
  .define(User, async ({ faker }) => {
    return {
      roleId: 1,
      fullName: faker.person.fullName(),
      email: faker.internet.email(),
      password: 'something',
    }
  })
  .build()

Factory Relationships

By adding relationships to our factories, we're giving ourselves the ability to create a fake challenge with a fake creator and a bunch of fake participants without having to specify any data. We can easily define a factory relationship using the relation() method. We'll pass the property name of the relationship as the first argument and give a callback function returning that relationship's factory as the second.

// database/factories/user_factory.ts
import User from '#models/user'
import factory from '@adonisjs/lucid/factories'
import { ChallengeFactory } from './challenge_factory.ts'
import { ProfileFactory } from './profile_factory.ts'

export const UserFactory = factory
  .define(User, async ({ faker }) => {
    return {
      roleId: 1,
      fullName: faker.person.fullName(),
      email: faker.internet.email(),
      password: faker.internet.password(),
    }
  })
  .relation('challenges', () => ChallengeFactory)
  .relation('createdChallenges', () => ChallengeFactory)
  .relation('profile', () => ProfileFactory)
  .build()

Let's go ahead and fill in the profile's relationship to the user.

// database/factories/profile_factory.ts
import Profile from '#models/profile'
import factory from '@adonisjs/lucid/factories'
import { UserFactory } from './user_factory.ts'

export const ProfileFactory = factory
  .define(Profile, async ({ faker }) => {
    return {
      bio: faker.person.bio(),
      isPublic: faker.datatype.boolean(),
    }
  })
  .relation('user', () => UserFactory)
  .build()

Finally, our challenge's relationship mirrors our user.

// database/factories/challenge_factory.ts
import Challenge from '#models/challenge'
import factory from '@adonisjs/lucid/factories'
import { UserFactory } from './user_factory.ts'

export const ChallengeFactory = factory
  .define(Challenge, async ({ faker }) => {
    return {
      text: faker.git.commitMessage(),
      points: faker.number.int({ min: 1, max: 100 }),
    }
  })
  .relation('createdBy', () => UserFactory)
  .relation('participants', () => UserFactory)
  .build()

Using Factories

Now that we have our factories filled out, we can use them to create dummy data for our development environment using our DevSeeder. Like our model, factories also have a create() method. However, since the instance is filled with our faker dummy data, we don't need to specify any data for it!

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // Write your database queries inside the run method
    await ChallengeFactory.create()
  }
}

One challenge isn't much for dummy data, though. Let's create a lot using createMany() instead! All we need to do is tell it how many challenges to create, and it'll do the rest. Let's make 50!

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // Write your database queries inside the run method
    await ChallengeFactory.createMany(50)
  }
}

Our challenges also need a creator, that's a not-nullable property. So, to include a creator with our challenge, we can use its createdBy relationship to include a fake user with each fake factory.

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // Write your database queries inside the run method
    await ChallengeFactory.with('createdBy', 50).createMany(50)
  }
}

Our creator could also use a profile, though. To include a nested relationship, we can include a third argument to get access to our UserFactory builder to include a profile for the user.

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // Write your database queries inside the run method
    await ChallengeFactory
      .with('createdBy', 50, (builder) => builder.with('profile'))
      .createMany(50)
  }
}

This will create 50 challenges with 50 users, one creator per challenge. What if we instead wanted a pool of 10 creators to randomly spread across our 50 challenges? Well, we could start by first creating our users.

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { UserFactory } from '#database/factories/user_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // create 10 users and grab their ids
    const creators = await UserFactory.with('profile').createMany(10)
    const creatorIds = creators.map((user) => user.id)

    await ChallengeFactory.createMany(50)
  }
}

Then, we can tap() into each challenge prior to it being persisted to randomly set which of our creatorIds get set as that challenge's creatorId.

// database/seeders/dev_seeder.ts
import { ChallengeFactory } from '#database/factories/challenge_factory'
import { UserFactory } from '#database/factories/user_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // create 10 users and grab their ids
    const creators = await UserFactory.with('profile').createMany(10)
    const creatorIds = creators.map((user) => user.id)

    // create 50 challenges with a random creator
    await ChallengeFactory.tap((challenge, { faker }) => {
      challenge.creatorId = faker.helpers.arrayElement(creatorIds)
    }).createMany(50)
  }
}

The tap() method is run once for each challenge being created. It receives an individual challenge model instance as its first parameter and the FactoryContext as its second parameter. So, we have faker at our disposal and faker contains a helper, arrayElement, that returns a random item from the provided array. In turn, this gets us a random user from our pool of created users.

Finally, we could use some participants. However, to do those from a pool of users as we did with our creators, we would need to be familiar with creating Lucid relationships. Let's not jump ahead and instead just create 6 participants per challenge.

import { ChallengeFactory } from '#database/factories/challenge_factory'
import { UserFactory } from '#database/factories/user_factory'
import { BaseSeeder } from '@adonisjs/lucid/seeders'

export default class extends BaseSeeder {
  static environment: string[] = ['development']

  async run() {
    // create 10 users and grab their ids
    const creators = await UserFactory.with('profile').createMany(10)
    const creatorIds = creators.map((user) => user.id)

    // create 50 challenges with a random creator
    await ChallengeFactory.tap((challenge, { faker }) => {
      challenge.creatorId = faker.helpers.arrayElement(creatorIds)
    })
      .with('participants', 6, (builder) => builder.with('profile'))
      .createMany(50)
  }
}

We've already run our DefaultSeeder, so specify that we specifically want to run our DevSeeder via the db:seed Ace CLI command.

node ace db:seed --files=database/seeders/dev_seeder  

A couple of things to note:

1. The --files option should point to the seeder file from the application root

2. Factories are created in a transaction, and we're creating many records with individual operations, so this may take a second

With that, if we boot our application back up with npm run dev and head back into our /challenges page, we should see 50 challenges, each with varying point values!

If you're interested in learning more about using factories, especially in tests, check out our series on testing with Japa!

If you'll recall, we were mimicking create, read, and update operations within our ChallengesController using an in-memory array. Let's work on transitioning that to use our database instead.

Creating Records

At the moment, we're just pushing a new challenge into an array defined above our controller's class.

// app/controllers/challenges_controller.ts
const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

    challenges.push({ id: challenges.length + 1, ...data })

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

What we want to do instead, to use our database, is import our Challenge model. If you'll recall from our last lesson, a model instance represents a single row within our table. So, by instantiating an instance of our Challenge model we're creating a representation of a new row in our challenges table.

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

++    const challenge = new Challenge()

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

However, just instantiating a new instance won't automatically populate it with our data, nor will it create or persist the row inside our table. We need to do those as well, and again, we have a couple of options. First, we can be verbose and manually populate each column/property of our new model instance.

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

    const challenge = new Challenge()

++    challenge.text = data.text
++    challenge.points = data.points

++    await challenge.save()

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

When we call await challenge.save() that is where the current values are held on our challenge instance are persisted into the database. An alternative to explicitly populating each column in our model is to merge them. This pairs fantastically with validated data that matches the structure of our model, as we have here, because it results in super clean code!

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

    const challenge = new Challenge()

++    challenge.merge(data)

    await challenge.save()

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

Might not be a huge difference with our small model, but it comes in very handy with larger models! Even better yet, we can condense the entire creation to a single line using our model's static create method. The create method essentially does exactly what we previously had, just in a smaller package, allowing us to create a challenge with just:

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

++    const challenge = await Challenge.create(data)

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

Though this does return the newly created model instance representing the row we've just persisted into the database, we don't need to make use of that at all here, so we can just omit that so we aren't leaving an unused variable.

// app/controllers/challenges_controller.ts
import Challenge from '#models/challenge'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response, session }: HttpContext) {
    const data = await challengeValidator.validate(request.all())

++    await Challenge.create(data)

    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

Note, there's also a createMany() method that allows us to create many records at once by providing an array of the data we want to create. This will also return an array of the created instances.

const challenges = await Challenge.createMany([
  challengeDataOne,
  challengeDataTwo
])

An Aside About Foreign Keys & REPL

One issue, though, our challenges table has a not null creator_id column within it. So, if we were to attempt to create a challenge, we'll get:

 insert into `challenges` (`created_at`, `points`, `text`, `updated_at`) values ('2026-02-05 00:12:16', 20, 'testing', '2026-02-05 00:12:16') - NOT NULL constraint failed: challenges.creator_id

We also can't just plop any ol' number in as a creator_id because we have a foreign key constraint on this column requiring it to hold a value existing within our users.id.

async store({ request, response, session }: HttpContext) {
  const data = await challengeValidator.validate(request.all())

++  await Challenge.create({ creatorId: 1, ...data })

  session.flash('success', 'Challenge created successfully')

  return response.redirect().toRoute('challenges.index')
}

If we were to try, we'd get:

insert into `challenges` (`created_at`, `creator_id`, `points`, `text`, `updated_at`) values ('2026-02-05 00:18:53', 1, 50, 'testing', '2026-02-05 00:18:53') - FOREIGN KEY constraint failed

Thankfully, the AdonisJS starter kit came with working authentication, so we could solve this by quickly registering a user. However, our user will have the same problem because it requires a role_id, but our roles table is empty at the moment.

In the next lesson, we'll see how we can remedy this situation with seeders. For now, we can actually jump into a Read-Evaluate Print Loop (REPL) session to quickly create a role. A REPL session is like a scratch pad version of our environment. To enter it, head into your terminal and run node ace repl.

node ace repl

# Type ".ls" to a view list of available context methods/properties
# > (js) 

If you type .ls and hit enter, you'll see a list of all available methods & properties.

> (js) .ls

GLOBAL METHODS:
importDefault         Returns the default export for a module
importAll             Import all files from a directory and assign them to a variable
make                  Make class instance using "container.make" method
loadApp               Load "app" service in the REPL context
loadEncryption        Load "encryption" service in the REPL context
loadHash              Load "hash" service in the REPL context
loadRouter            Load "router" service in the REPL context
loadConfig            Load "config" service in the REPL context
loadTestUtils         Load "testUtils" service in the REPL context
loadHelpers           Load "helpers" module in the REPL context
loadUrlBuilder        Load "urlBuilder" service in the REPL context
loadModels            Recursively load Lucid models to the "models" property
loadDb                Load database provider to the "db" property
loadFactories         Recursively load factories to the "factories" property
clear (propertyName)  Clear a property from the REPL context
p (function)          Promisify a function. Similar to Node.js "util.promisify"

CONTEXT PROPERTIES/METHODS:
{}

What we're after is the loadModels() method. This will make our models available via a models property.

await loadModels()
# recursively reading models from "app/models"
# Loaded models module. You can access it using the "models" variable
# > (js) undefined

This will execute the method and show us what it returned, which was undefined. We can then use the loaded models to create a new role, same as we did in our controller.

await models.role.create({ name: 'User' })
# "sqlite" Role (2 ms) INSERT INTO `roles` (`created_at`, `name`, `updated_at`) VALUES (?, ?, ?) [ '2026-02-05 00:34:55', 'User', '2026-02-05 00:34:55' ]
# Role {
#   modelOptions: undefined,
#   modelTrx: undefined,
#   transactionListener: [Function: bound listener],
#   fillInvoked: false,
#   cachedGetters: {},
#   forceUpdate: false,
#   '$columns': [ 'id', 'name', 'createdAt', 'updatedAt' ],
#   '$attributes': {
#     name: 'User',
#     createdAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US },
#     updatedAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US },
#     id: 1
#   },
#   '$original': {
#     name: 'User',
#     createdAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US },
#     updatedAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US },
#     id: 1
#   },
#   '$preloaded': {},
#   '$extras': {},
#   '$sideloaded': {},
#   '$isPersisted': true,
#   '$isDeleted': false,
#   '$isLocal': true,
#   name: 'User',
#   createdAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US },
#   updatedAt: DateTime { ts: 2026-02-05T00:34:55.652+00:00, zone: UTC, locale: en-US }
# }

As you can see, our create() method returned the newly created instance of our role model! Since it's the first role that's been created in the table, it was given the ID of 1. Let's go ahead and do the same for our user while we're here. Alternatively, you could use the signup form on our site.

> (js) await models.user.create({
|   fullName: 'Tom Gobich',
|   email: 'tom@adocasts.com',
  | password: 'something'
| })
# "sqlite" User (1.85 ms) INSERT INTO `users` (`created_at`, `email`, `full_name`, `password`, `updated_at`) VALUES (?, ?, ?, ?, ?) [
#   '2026-02-05 00:41:22',
#   'tom@adocasts.com',
#   'Tom Gobich',
#   '$scrypt$n=16384,r=8,p=1$fLEoMihP9M2nDqxhtGFWCA$pMgwjKJE1WhRMcAgLvEMCha54J7rcVbapRQF7QSpgMxn1j6WUuW7CIdK6r7yYISJojEdhbMvWnqelb6ujGcU5Q',
#   '2026-02-05 00:41:22'
# ]
# User {
#   modelOptions: undefined,
#   modelTrx: undefined,
#   transactionListener: [Function: bound listener],
#   fillInvoked: false,
#   cachedGetters: {},
#   forceUpdate: false,
#   '$columns': [
#     'id',
#     'roleId',
#     'fullName',
#     'email',
#     'password',
#     'createdAt',
#     'updatedAt'
#   ],
#   '$attributes': {
#     fullName: 'Tom Gobich',
#     email: 'tom@adocasts.com',
#     password: '$scrypt$n=16384,r=8,p=1$fLEoMihP9M2nDqxhtGFWCA$pMgwjKJE1WhRMcAgLvEMCha54J7rcVbapRQF7QSpgMxn1j6WUuW7CIdK6r7yYISJojEdhbMvWnqelb6ujGcU5Q',
#     createdAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US },
#     updatedAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US },
#     id: 1
#   },
#   '$original': {
#     fullName: 'Tom Gobich',
#     email: 'tom@adocasts.com',
#     password: '$scrypt$n=16384,r=8,p=1$fLEoMihP9M2nDqxhtGFWCA$pMgwjKJE1WhRMcAgLvEMCha54J7rcVbapRQF7QSpgMxn1j6WUuW7CIdK6r7yYISJojEdhbMvWnqelb6ujGcU5Q',
#     createdAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US },
#     updatedAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US },
#     id: 1
#   },
#   '$preloaded': {},
#   '$extras': {},
#   '$sideloaded': {},
#   '$isPersisted': true,
#   '$isDeleted': false,
#   '$isLocal': true,
#   fullName: 'Tom Gobich',
#   email: 'tom@adocasts.com',
#   password: '$scrypt$n=16384,r=8,p=1$fLEoMihP9M2nDqxhtGFWCA$pMgwjKJE1WhRMcAgLvEMCha54J7rcVbapRQF7QSpgMxn1j6WUuW7CIdK6r7yYISJojEdhbMvWnqelb6ujGcU5Q',
#   createdAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US },
#   updatedAt: DateTime { ts: 2026-02-05T00:41:22.828+00:00, zone: UTC, locale: en-US }
# }

A few things to note here.

1. REPL is smart enough to know not to execute when line breaks are entered with unclosed blocks, allowing new lines as we enter an object's details.

2. Our password was entered as something, but was persisted into the database as $scrypt$n=163.... This is done automatically for us via an @beforeSave() hook added onto our User model by AdonisJS's authentication. We'll discuss this more later in the series.

Fantastic! We've now got our role and user, so we can exit our REPL session by typing .exit and hitting enter. Let's then boot our server back up and try creating a challenge once more.

If all went according to plan, we should see our "Challenge created successfully" toast message and be redirected back to challenges.index. However, we're still reading from our in-memory array so we don't see it within our list. Let's fix that next.

Reading Data

Our models provide a number of different ways to query data from our database because getting data is never a one-size-fits-all problem. In this lesson, we'll only be looking at the static method options available for querying data. These static methods are for simple and common use-cases, but do note that our models also have a query builder on them to allow complex queries. We'll introduce that a little later on.

Starting simple, we can grab everything in our challenges table using the static all() method. I'll call our variable list here because challenges is still in use.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
++    const list = await Challenge.all()
++    return view.render('pages/challenges/index', { challenges: list })
  }

  // ...
}

If you refresh your page, you should now see the challenge or challenges you've persisted thus far into your database. Anything more complex than this, and you'd want to reach for the query builder, again, more on that later.

When trying to get at a single record, we have a few static options. First, we can find() a row by providing it's id as the argument.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.find(params.id)
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

This will attempt to find a challenge with the provided ID and return null if one cannot be found. We can also findBy(), providing a column we want to search against in the first argument and the value in the second.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  // ...

  /**
   * Show individual record
   */
  async show({ view, params }: HttpContext) {
++    const challenge = await Challenge.findBy('id', params.id)
    const editUrl = urlFor('challenges.edit', { id: params.id })

    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Note, this can also be written as await Challenge.findBy({ id: params.id }). Both of these also have many variants, allowing you to provide more than one value as an array. These will return an array of all records that've matched your search. For example,

const challenges = await Challenge.findMany([1, 2, 3])

Both, find() and findBy() also have a fail variant too. Unlike the base version, if the fail variant cannot find a record matching your search, it will throw a 404 Not Found exception.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
++    const challenge = await Challenge.findOrFail(params.id)

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  // ...
}

Updating Data

When it comes to updating data, it is relatively similar to creating. The primary difference is that we'll want to query for the record instead of instantiating a new instance.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the edit action
   */
  async update({ params, request, response }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)
++    const challenge = await Challenge.findOrFail(params.id)

++    challenge.merge(data)

++    await challenge.save()

    return response.redirect().toRoute('challenges.show', { id: params.id })
  }

  // ...
}

Similar to the create() method, there's also a shorthand for updating, called updateOrCreate(). Note, it will fall back to creating a new record if a match cannot be found. So, only use it if you're okay with that possibility.

// app/controllers/challenges_controller.ts
const challenges = [{ ... }]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the edit action
   */
  async update({ params, request, response }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)

++    await Challenge.updateOrCreate({ id: params.id }, data)

    return response.redirect().toRoute('challenges.show', { id: params.id })
  }

  // ...
}

It will attempt to find the record with the payload provided as the first argument. If it finds a match, it'll update the matched record with the data provided in the second argument. If it does not find a match, it'll merge the first and second arguments together to create a record.

Again, like create(), there's also an updateOrCreateMany() version. It accepts an array of data to update or create with.

const challenges = await Challenge.updateOrCreate({ text: 'Test' }, [dataOne, dataTwo])

Deleting Records

Deleting records in AdonisJS is rather straightforward; we just need to query for the record and call it's delete() method. Once run, it'll delete that record from our database.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Delete record
   */
  async destroy({ params, response, session }: HttpContext) {
    const challenge = await Challenge.findOrFail(params.id)

    await challenge.delete()

    session.flash('success', `${challenge.text} has been deleted`)

    return response.redirect().toRoute('challenges.index')
  }
}

Next, let's add a form on our challenges.show page to let us easily delete. I'm going to put the button outside of the form so we don't need to bugger with tweaking any of the starter kit's CSS.

// resources/views/pages/challenges/show.edge
@layout()

  <div class="hero">
    <h1>{{ challenge.text }}</h1>
    <p>Points: {{ challenge.points }}</p>

    <a href="{{ editUrl }}" class="button">Edit Challenge</a>
    <button type="submit" form="destroy" class="button destructive">Delete</button>
  </div>

  @!form({ id: 'destroy', route: 'challenges.destroy', routeParams: { id: challenge.id }, method: 'DELETE' })

@end

With that added, if we click our "Delete" button, we should see our success toast and be redirected back to the challenges.index page! However, one thing to note. When we delete, we need to ensure our foreign key constraints are enforced; otherwise, the delete will fail.

We could do this by cascading the delete within our database. That can be done via the migration, like below.

// database/migrations/xxxxxx_create_challenge_users_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'challenge_user'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table
        .integer('challenge_id')
        .unsigned()
        .references('challenges.id')
        .notNullable()
++        .onDelete('CASCADE')
      table
        .integer('user_id')
        .unsigned()
        .references('users.id')
        .notNullable()
++        .onDelete('CASCADE')

      table.timestamp('completed_at')
      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

With this, when we delete a challenge any challenge_user records using that challenge's ID will also automatically be deleted.

So, you could choose that option, or you could manually handle the foreign key references when deleting. For that, we can reach through to specific relationships using the related() method on our model instance and detach or delete related records.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Delete record
   */
  async destroy({ params, response, session }: HttpContext) {
    const challenge = await Challenge.findOrFail(params.id)

++    await challenge.related('participants').detach()
    await challenge.delete()

    session.flash('success', `${challenge.text} has been deleted`)

    return response.redirect().toRoute('challenges.index')
  }
}

In most databases, the foreign key references must be deleted before the record itself can be deleted, so we'll detach before we delete the record. We'll be discussing working with relationships in a dedicated lesson, so more on that later.

What Are Schemas Classes?

New in AdonisJS 7, schema classes are generated from a migration-first approach to represent the tables in our database after migration. Though they're auto-generated, they are meant to be used and don't merely represent types. For that reason, they aren't housed within our .adonisjs folder, but instead within database/schema.ts.

This schema.ts file will contain exported schema classes for all the tables within our database. Each class describes a table's columns and the column's types. For example, here is our UserSchema describing our users table.

// database/schema.ts
export class UserSchema extends BaseModel {
  static $columns = ['id', 'roleId', 'fullName', 'email', 'password', 'createdAt', 'updatedAt'] as const
  $columns = UserSchema.$columns
  @column({ isPrimary: true })
  declare id: number
  @column()
  declare roleId: number
  @column()
  declare fullName: string | null
  @column()
  declare email: string
  @column({ serializeAs: null })
  declare password: string
  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime
  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime | null
}

The @column() decorators on top of each property notes that the property represents a column in our database. Any properties without the @column() decorator are then what we call not-mapped, meaning they aren't mapped to the database directly. Our database convention is to use snake case, but the JavaScript convention is to use camelCase in code. Lucid is already expecting both of these conventions and will handle that transition from snake case in our database to camel case in our models without issue.

Nullable columns are noted via their type.

@column()
declare fullName: string | null

The primary key column is specially noted for the ORM's convenience.

@column({ isPrimary: true })
declare id: number

We can omit a property from all serializations by setting the serializeAs property of the @column() decorator's config to null.

@column({ serializeAs: null })
declare password: string

Finally, we can mutate the timestamp columns to Luxon DateTimes by adding @column.dateTime().

@column.dateTime({ autoCreate: true, autoUpdate: true })
declare updatedAt: DateTime | null

On these, setting autoCreate to true will auto-set the value to the current date and time when a record is created or inserted into our table. Then, setting autoUpdate to true will auto-update the value to the current date and time when a record is updated within the table.

You might've also noticed these schema classes are extending a BaseModel class. This BaseModel is the powerhouse of the ORM, taking this mapping and making it usable so we can query or mutate data within the table using what will eventually be our models.

What Are Models?

Models are a specialized class that represents a single table within our database. Properties within the class represent columns of the table. Finally, an instance of the class represents a single row of data within the table.

These model representations act as a translator, allowing us to describe the queries or operations in TypeScript. It then converts it to SQL, executes it, and translates the results back into TypeScript for us to use.

Let's use the Ace CLI's make:model command to create a model for our roles table.

node ace make:model role
# DONE:    create app/models/role.ts

Since an instance of a model represents a single row, the convention is to use a singular name for the model.

Also, with the make:model command, we can create additional things like migrations, controllers, and factories!

> $ node ace make:model --help

Description:
  Make a new Lucid model

Usage:
  node ace make:model [options] [--] <name>

Arguments:
  name              Name of the model class

Options:
  -m, --migration   Generate the migration for the model
  -c, --controller  Generate the controller for the model
  -f, --factory     Generate a factory for the model

As noted by our DONE statement from our make:model command, we can find our models within the app/models/ directory. If we open our Role model, we should see the following.

// app/models/role.ts
import { RoleSchema } from '#database/schema'

export default class Role extends RoleSchema {
}

As you can see, it's merely a class extending our RoleSchema.

// database/schema.ts
export class RoleSchema extends BaseModel {
  static $columns = ['id', 'name', 'createdAt', 'updatedAt'] as const
  $columns = RoleSchema.$columns
  @column({ isPrimary: true })
  declare id: number
  @column()
  declare name: string
  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime | null
  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime | null
}

The RoleSchema's job is to describe the columns of our roles table. It's housed within a class of its own, so it can be easily auto-generated without breaking the other mappings we'll add to our model. If you have any columns that need to be altered from their auto-generated schema representation, they can be overridden inside our model.

For example, say our role's name column was role_name in the database, but we wanted to just call it name in the model, we could do the following.

// app/models/role.ts
import { RoleSchema } from '#database/schema'
++import { column, hasMany } from '@adonisjs/lucid/orm'
import type { HasMany } from '@adonisjs/lucid/types/relations'
import User from './user.ts'

export default class Role extends RoleSchema {
++  @column({ columnName: 'role_name' })
++  declare name: string

  @hasMany(() => User)
  declare users: HasMany<typeof User>
}

Model Relationships

So, what are those other mappings we'll add to our model? One mapping we'll have is for relationships. Relationship mappings allow us to describe that a user has one role and a role can have many users, for example.

This ultimately will allow us to then query a user record and load it along with its role record, so we can display the role via user.role.name. Or, conversely, a role with an array of its users.

In our Role model, we can do this by adding a users property and decorating it with Lucid's @hasMany() decorator. This decorator is then passed in, via callback, the related model (our User). Each relationship also has its own type that accepts a generic of the type of the related model as well.

import { RoleSchema } from '#database/schema'
++import { hasMany } from '@adonisjs/lucid/orm'
++import type { HasMany } from '@adonisjs/lucid/types/relations'
++import User from './user.ts'

export default class Role extends RoleSchema {
++  @hasMany(() => User)
++  declare users: HasMany<typeof User>
}

AdonisJS has a convention it follows for defaults on our relationship, all of which can be overwritten by providing them as options in the second argument of the decorator.

• localKey - the local primary key, defaulting to the primary key of the parent model, id in our case.

• foreignKey - the related primary key, defaulting to a camel case concatenation of the parent model name followed by its primary key, roleId in our case.

There are five different types of relationships:

1. hasOne - a user has one profile

2. hasMany - a role has many users

3. belongsTo - a profile belongs to a user

4. manyToMany - a challenge has many users, and a user can have many challenges

5. hasManyThrough - a role can have created many challenges through its user

All of these relationship options, except those prefixed with pivot, like pivotForeignKey, should use our model's name for the column (roleId) instead of the table's name (role_id). The pivot options are an exception because, as we'll see in a bit, pivot tables are represented by a many-to-many relationship instead of a model.

Let's go ahead and jump over to our User model to describe the inverse side of this relationship. You'll notice there's more going on with our User model. That's okay, for now, let's focus on the task at hand!

// app/models/user.ts
import { UserSchema } from '#database/schema'
import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
import { compose } from '@adonisjs/core/helpers'
import hash from '@adonisjs/core/services/hash'
++import { belongsTo } from '@adonisjs/lucid/orm'
++import type { BelongsTo } from '@adonisjs/lucid/types/relations'
++import Role from './role.ts'

/**
 * User model represents a user in the application.
 * It extends UserSchema and includes authentication capabilities
 * through the withAuthFinder mixin.
 */
export default class User extends compose(UserSchema, withAuthFinder(hash)) {
++  @belongsTo(() => Role)
++  declare role: BelongsTo<typeof Role>

  /**
   * Get the user's initials from their full name or email.
   * Returns the first letter of first and last name if available,
   * otherwise returns the first two characters of the email username.
   */
  get initials() {
    const [first, last] = this.fullName ? this.fullName.split(' ') : this.email.split('@')
    if (first && last) {
      return `${first.charAt(0)}${last.charAt(0)}`.toUpperCase()
    }
    return `${first.slice(0, 2)}`.toUpperCase()
  }
}

Typically, if the relationship ID is described on the model, it'll be a BelongsTo relationship. Since our Users model consists of a roleId column, that's exactly the case here.

Getters & Computed Properties

Okay, while we're on our User model, let's talk about get initials(). This is a getter, and it'll act just like a property, though executing the method when used to return the value. These are non-mapped properties, meaning they aren't present in our database, that we can add onto our models to aid in development. Note, getters cannot be asynchronous; this is a limitation of the language, not the framework.

Like getters, we can define whatever properties or methods we want on our models. So long as the @column() and relationship decorators are omitted, they'll be treated as non-mapped properties.

They are, however, omitted when the model is serialized by default. So, when our models are converted to JSON, for example, these properties will be omitted. If we want them to be included, we can decorate them with the @computed() decorator.

// app/models/user.ts
import { UserSchema } from '#database/schema'
import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
import { compose } from '@adonisjs/core/helpers'
import hash from '@adonisjs/core/services/hash'
++import { belongsTo, computed } from '@adonisjs/lucid/orm'
import type { BelongsTo } from '@adonisjs/lucid/types/relations'
import Role from './role.ts'

/**
 * User model represents a user in the application.
 * It extends UserSchema and includes authentication capabilities
 * through the withAuthFinder mixin.
 */
export default class User extends compose(UserSchema, withAuthFinder(hash)) {
  @belongsTo(() => Role)
  declare role: BelongsTo<typeof Role>

  /**
   * Get the user's initials from their full name or email.
   * Returns the first letter of first and last name if available,
   * otherwise returns the first two characters of the email username.
   */
++  @computed()
  get initials() {
    const [first, last] = this.fullName ? this.fullName.split(' ') : this.email.split('@')
    if (first && last) {
      return `${first.charAt(0)}${last.charAt(0)}`.toUpperCase()
    }
    return `${first.slice(0, 2)}`.toUpperCase()
  }
}

With this decorator added to the property, it informs AdonisJS to keep the property within the serialized result.

Great, while we're here, let's create our remaining two models and fill in their relationships.

node ace make:model profile
# DONE:    create app/models/profile.ts

node ace make:model challenges
# DONE:    create app/models/challenge.ts

Again, we won't be creating a model for our challenge_user pivot table. Pivot tables can be omitted and worked with directly via their many-to-many relationship within the ORM.

Our Profile model has the userId column on it, so our profile belongs to a user.

import { ProfileSchema } from '#database/schema'
++import { belongsTo } from '@adonisjs/lucid/orm'
++import User from './user.ts'
++import type { BelongsTo } from '@adonisjs/lucid/types/relations'

export default class Profile extends ProfileSchema {
++  @belongsTo(() => User)
++  declare user: BelongsTo<typeof User>
}

Then, for our Challenge model, challenges belong to a user in two different ways.

1. They're created by a user, tracked via the creatorId

2. They have users who've joined the challenge via our challenge_user pivot table

// app/models/challenge.ts
import { ChallengeSchema } from '#database/schema'
++import { belongsTo, manyToMany } from '@adonisjs/lucid/orm'
++import type { BelongsTo, ManyToMany } from '@adonisjs/lucid/types/relations'
++import User from './user.ts'

export default class Challenge extends ChallengeSchema {
++  @belongsTo(() => User, {
++    foreignKey: 'creatorId',
++  })
++  declare createdBy: BelongsTo<typeof User>

++  @manyToMany(() => User)
++  declare participants: ManyToMany<typeof User>
}

Since we're straying from the default naming convention of userId (parent model name + primary key) with our creatorId, we need to manually specify that as the foreign key for our BelongsTo relationship. Also, we can call the property name whatever we'd like for relationships, which gives us nice flexibility to be descriptive.

Then, for our ManyToMany, the options look a little different, should you need to use them.

• localKey - primary key of the current model

• pivotForeignKey - pivot table's foreign key for current model (use the table column name)

• relatedKey - primary key of the related model

• pivotRelatedForeignKey - pivot table's foreign key for the related model (use the table column name)

We don't need to, because we match the default convention, but if we manually describe this relationship's keys, it'd look like this:

// app/models/challenge.ts
export default class Challenge extends ChallengeSchema {
  // ...

  @manyToMany(() => User, {
    localKey: 'id',
    pivotForeignKey: 'challenge_id',
    relatedKey: 'id',
    pivotRelatedForeignKey: 'user_id',
  })
  declare participants: ManyToMany<typeof User>
}

Finally, we can fill in the remaining relationships of our User model.

import { UserSchema } from '#database/schema'
import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
import { compose } from '@adonisjs/core/helpers'
import hash from '@adonisjs/core/services/hash'
++import { belongsTo, computed, hasMany, hasOne, manyToMany } from '@adonisjs/lucid/orm'
++import type { BelongsTo, HasMany, HasOne, ManyToMany } from '@adonisjs/lucid/types/relations'
++import Challenge from './challenge.ts'
++import Profile from './profile.ts'
import Role from './role.ts'

/**
 * User model represents a user in the application.
 * It extends UserSchema and includes authentication capabilities
 * through the withAuthFinder mixin.
 */
export default class User extends compose(UserSchema, withAuthFinder(hash)) {
  @belongsTo(() => Role)
  declare role: BelongsTo<typeof Role>

++  @hasOne(() => Profile)
++  declare profile: HasOne<typeof Profile>

++  @hasMany(() => Challenge, {
++    foreignKey: 'creatorId',
++  })
++  declare createdChallenges: HasMany<typeof Challenge>

++  @manyToMany(() => Challenge)
++  declare challenges: ManyToMany<typeof Challenge>

  /**
   * Get the user's initials from their full name or email.
   * Returns the first letter of first and last name if available,
   * otherwise returns the first two characters of the email username.
   */
  @computed()
  get initials() {
    const [first, last] = this.fullName ? this.fullName.split(' ') : this.email.split('@')
    if (first && last) {
      return `${first.charAt(0)}${last.charAt(0)}`.toUpperCase()
    }
    return `${first.slice(0, 2)}`.toUpperCase()
  }
}

Again, since our creatorId goes against the default naming convention, we'll specify the foreign key as creatorId here.

Model Hooks

Finally, although we haven't talked about create, read, update, or delete (CRUD) operations, let's take a moment to learn about hooks. They are specialized static methods defined on our models that can hook into certain operations being performed with our models. For example, we could hook into our Profile model to mutate it before it is persisted to the database.

import { ProfileSchema } from '#database/schema'
++import { beforeSave, belongsTo } from '@adonisjs/lucid/orm'
import type { BelongsTo } from '@adonisjs/lucid/types/relations'
import User from './user.ts'

export default class Profile extends ProfileSchema {
  @belongsTo(() => User)
  declare user: BelongsTo<typeof User>

++  @beforeSave()
++  static onBeforeSave(profile: Profile) {
++    if (profile.$dirty.bio && !profile.bio) {
++      profile.bio = '[no bio]'
++    }
++  }
}

The name of the method doesn't matter; all that matters is that the method is static and is decorated with @beforeSave(). With that, Lucid will run the method before creating or updating a profile record in our database.

A little redundant, but we can also use special properties on our model, like $dirty for example, to see if one of our columns has been altered at all.

Available Hooks

All of the below hooks can be async, and all are provided the model instance/row being mutated.

• @beforeSave() - run before an insert or update operation

• @afterSave() - run after an insert or update operation

• @beforeCreate() - run before an insert operation

• @afterCreate() - run after an insert operation

• @beforeUpdate() - run before an update operation

• @afterUpdate() - run after an update operation

• @beforeDelete() - run before a delete operation

• @afterDelete() - run after a delete operation

There are also query-based hooks that receive either the query (before) or the results of the query (after).

• @beforeFind() - run before find queries

• @afterFind() - run after find queries

• @beforeFetch() - run before fetch queries

• @afterFetch() - run after fetch queries

• @beforePaginate() - run before pagination queries

• @afterPaginate() - run after pagination queries

1. They allow teammates to easily onboard into the project and/or keep their development database up-to-date.

2. They allow code changes to go out in unison with database changes in our production environment.

Migration Basics

AdonisJS migrations can be found within the database/migrations directory, and if we look there, we can see our starter kit has given us one to start with. You might note its filename:

database/migrations/1758943358073_create_users_table.ts

The number at the beginning of the filename, 1758943358073, is a timestamp of when the migration was created. This is used to naturally sort our migrations, both in our migrations folder and in the order they'll run, giving us a consistent and reliable order for them.

After the timestamp, is the action of the migration, create_users_table, noting that this migration creates the users table within our database. This is purely for informative reasons to help us find specific migrations in our file tree; these may be as simple as the table's name.

Migrations are comprised of a class extending a BaseSchema from Lucid, AdonisJS's Object Relational Mapping (ORM). ORMs are like a translator, taking an object-like representation we'll use in TypeScript and translating it to the relational tables in our database. This gives us simplified syntax for things like querying data or even building tables, like we'll do with migrations.

// database/migrations/xxxxx_create_users_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable()
      table.string('full_name').nullable()
      table.string('email', 254).notNullable().unique()
      table.string('password').notNullable()

      table.timestamp('created_at').notNullable()
      table.timestamp('updated_at').nullable()
    })
  }

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

Within the migration class are two methods, up and down. The up method is forward progress. This is where we'll create new tables, constraints, or any other changes to our database we want to apply. The down method allows us to go backward, or undo anything we've done in the up method.

Whatever we do in up we should undo in down. For example, in the users migration above, the up method creates the users table within our database, while the down method drops the users table.

This flow is primarily to aid in development, allowing incremental progress or change without having to create tons of migrations for a single feature. The down method is destructive and shouldn't be run in production, and AdonisJS will require confirmation in order to do so.

Running Migrations

When a migration is run, the up method will be executed. We can easily run migrations using the Ace CLI's migration:run command.

node ace migration:run
# [ error ] Cannot open database because the directory does not exist

When we first try to run our migration, we may see an error that the directory does not exist. By default, AdonisJS will use SQLite as its database. This is a file-based database that will be housed within our project's temporary directory (tmp). If you get this error, it's because that directory does not exist, so let's create it real quick!

mkdir tmp

Then, let's try our migration once more.

node ace migration:run
# "sqlite" (112 μs) SELECT `version` FROM `adonis_schema_versions` LIMIT ? [ 1 ]
# "sqlite" (627 μs) INSERT INTO `adonis_schema_versions` (`version`) VALUES (?) [ 1 ]
# [ info ] Upgrading migrations version from "1" to "2"
# "sqlite" (56 μs) SELECT `name`, `batch`, `migration_time`, `id` FROM `adonis_schema` WHERE `batch` > ? ORDER BY `id` DESC [ 0 ]
# "sqlite" (219 μs) UPDATE `adonis_schema_versions` SET `version` = ? WHERE `version` = ? [ 2, 1 ]
# "sqlite" (113 μs) SELECT MAX(`batch`) AS `batch` FROM `adonis_schema` []
# "sqlite" (44 μs) SELECT `name` FROM `adonis_schema` []
# ❯ migrating database/migrations/1758943358073_create_users_table
# (471 μs) CREATE TABLE `users` (`id` INTEGER NOT NULL PRIMARY KEY autoincrement, `full_name` VARCHAR(255) NULL, `email` VARCHAR(254) NOT NULL, `password` VARCHAR(255) NOT NULL, `created_at` DATETIME NOT NULL, `updated_at` DATETIME NULL)
# ❯ migrated database/migrations/1758943358073_create_users_table
# 
# Migrated in 53 ms
# "sqlite" (127 μs) SELECT `name` AS `table_name` FROM `sqlite_master` WHERE `type` = ? AND NOT `name` LIKE ? ORDER BY `name` ASC [ 'table', 'sqlite_%' ]
# ❯ Creating schema classes for scanned tables
# [ success ] Schema classes generated (4.63 ms)

A lot of information is printed out, detailing every SQL command the migration executed on our behalf. You can see that it first checks the adonis_schema_versions table. This is a table used to track Lucid's schema versioning; we don't need to worry about it.

"sqlite" (112 μs) SELECT `version` FROM `adonis_schema_versions` LIMIT ? [ 1 ]
"sqlite" (627 μs) INSERT INTO `adonis_schema_versions` (`version`) VALUES (?) [ 1 ]
[ info ] Upgrading migrations version from "1" to "2"
"sqlite" (219 μs) UPDATE `adonis_schema_versions` SET `version` = ? WHERE `version` = ? [ 2, 1 ]

Next, it checks for the last batch that was run. When we run our migrations, Lucid will run any migration that hasn't yet run. All migrations processed in a single run are considered a batch. It keeps track of all this information in a table called adonis_schema.

"sqlite" (56 μs) SELECT `name`, `batch`, `migration_time`, `id` FROM `adonis_schema` WHERE `batch` > ? ORDER BY `id` DESC [ 0 ]
"sqlite" (113 μs) SELECT MAX(`batch`) AS `batch` FROM `adonis_schema` []
"sqlite" (44 μs) SELECT `name` FROM `adonis_schema` []

Using that info, it determines which migrations within our database/migrations directory need to run, skipping those that have already run.

Small note, the question marks and square brackets in these queries are SQL Parameterization. A precautionary step that protects our database against SQL Injection Attacks. For example, it prevents someone from being able to drop a table in our database via an input shown on our web page. The hard brackets represent an array, and it works left to right to fill in each question mark placeholder within the query.

-- so a parameterized query, like this:
UPDATE `adonis_schema_versions` SET `version` = ? WHERE `version` = ? [ 2, 1 ]
-- will get run by SQL as this:
UPDATE `adonis_schema_versions` SET `version` = 2 WHERE `version` = 1

Next, it runs the up method from our migration.

❯ migrated database/migrations/1758943358073_create_users_table
 
Migrated in 53 ms

Finally, it generates schema classes from our database, we'll discuss these more in the next lesson.

"sqlite" (127 μs) SELECT `name` AS `table_name` FROM `sqlite_master` WHERE `type` = ? AND NOT `name` LIKE ? ORDER BY `name` ASC [ 'table', 'sqlite_%' ]
❯ Creating schema classes for scanned tables
[ success ] Schema classes generated (4.63 ms)

At this point, our database now contains an empty users table!

By the way, we'll be using these queries that are printed into our terminal throughout this module to aid in our understanding of what's happening. If, however, at any point you want to turn these off, you can easily do this within your database config.

// config/database.ts
import app from '@adonisjs/core/services/app'
import { defineConfig } from '@adonisjs/lucid'

const dbConfig = defineConfig({
  // ...

  connections: {
    sqlite: {
      // ...

      /**
       * Enable SQL query debugging in development mode.
       */
++      debug: app.inDev,
    },
  },
})

export default dbConfig

Rolling Back

When a migration is rolled back, the down method is run that should undo whatever was done in the migration's up method. Again, there is an Ace CLI command for this called migration:rollback.

node ace migration:rollback
# "sqlite" (119 μs) SELECT `version` FROM `adonis_schema_versions` LIMIT ? [ 1 ]
# "sqlite" (177 μs) SELECT MAX(`batch`) AS `batch` FROM `adonis_schema` []
# "sqlite" (84 μs) SELECT `name`, `batch`, `migration_time`, `id` FROM `adonis_schema` WHERE `batch` > ? ORDER BY `id` DESC [ 0 ]
# ❯ reverting database/migrations/1758943358073_create_users_table
# (905 μs) DROP TABLE `users`
# ❯ reverted database/migrations/1758943358073_create_users_table
# 
# Reverted in 27 ms
# "sqlite" (148 μs) SELECT `name` AS `table_name` FROM `sqlite_master` WHERE `type` = ? AND NOT `name` LIKE ? ORDER BY `name` ASC [ 'table', 'sqlite_%' ]
# ❯ Creating schema classes for scanned tables
# [ success ] Schema classes generated (2.43 ms)

Rollbacks occur one batch at a time, unless otherwise specified, so as we can see, it's querying for the max batch number in our adonis_schema table to then get all migrations in that batch.

"sqlite" (177 μs) SELECT MAX(`batch`) AS `batch` FROM `adonis_schema` []
"sqlite" (84 μs) SELECT `name`, `batch`, `migration_time`, `id` FROM `adonis_schema` WHERE `batch` > ? ORDER BY `id` DESC [ 0 ]

It'll then revert those migrations, running their down method.

❯ reverting database/migrations/1758943358073_create_users_table
(905 μs) DROP TABLE `users`
❯ reverted database/migrations/1758943358073_create_users_table
 
Reverted in 27 ms

Finally, again regenerating schemas from our updated database structure.

"sqlite" (148 μs) SELECT `name` AS `table_name` FROM `sqlite_master` WHERE `type` = ? AND NOT `name` LIKE ? ORDER BY `name` ASC [ 'table', 'sqlite_%' ]
❯ Creating schema classes for scanned tables
[ success ] Schema classes generated (2.43 ms)

At this point, we no longer have a users table within our database.

Before we move on, there are a few other Ace CLI commands to note here.

• migration:fresh will drop all tables and rerun all our migrations, essentially giving us a clean data slate.

• migration:refresh will rollback and remigrate, again, this will do a single batch unless otherwise specified.

• migration:reset will roll all the way back, undoing all migrations.

• migration:status will read our adonis_schema table to print out the status of all our migrations, showing which have run and which are pending.

Creating Migrations

We'll need more than just a users table and a migration should only consist of creations or alterations for a single table. If you need to make multiple tables or changes to multiple tables, we should create a new migration for each table we need to touch.

Like everything else, we can easily do this via the Ace CLI's make:migration command.

node ace make:migration role
# DONE:    create database/migrations/1770077349836_create_roles_table.ts

Notice how AdonisJS automatically normalized our table name to plural and gave us a starting create table structure with an auto-incrementing id in our up method and a dropTable statement in our down. Also note, convention states we should define our column names in snake case, meaning all lowercase using underscores to separate words.

// database/migrations/xxxxx_create_roles_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'roles'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')

      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

Okay, let's add a name column to our roles table!

// database/migrations/xxxxx_create_roles_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'roles'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
++      table.string('name').notNullable()

      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

We start with table and a method to describe the column's type, like string. Inside the type method goes the column's name. Off the type method, we can chain additional alterations for the column. By default, columns will be defined as nullable, so we can make this not null by chaining the notNullable() method on it.

Next, we need to be able to assign a user a role. So, let's add a role_id column to our create_users_table migration.

// database/migrations/xxxxx_create_users_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable()
++      table.integer('role_id').unsigned().references('id').inTable('roles').notNullable().defaultTo(1)
      table.string('full_name').nullable()
      table.string('email', 254).notNullable().unique()
      table.string('password').notNullable()

      table.timestamp('created_at').notNullable()
      table.timestamp('updated_at').nullable()
    })
  }

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

The column name role_id also comes from convention. A singular version of the referencing table (role), followed by that table's primary key (id), and joined together with an underscore.

The unsigned() method notes our integer type won't be negative. Then, references('id').inTable('roles') defines a foreign key constraint for role_id ensuring that any value inserted into it needs to exist within our roles.id. This can also be written as just references('roles.id'). Finally, we'll default the value to 1, which will eventually be our "user" role. If we create a user without a role_id specified, 1 will be used as the default.

Migration Order

Now, in most databases, the orderin which we create our migrations does matter. For our user to have a role_id on its table, for example, the roles table must be created first. Otherwise, we won't be able to add a foreign key constraint to ensure the user isn't being assigned a role that doesn't exist. SQLite has a lazy foreign key, though, so this won't be the case. We will, however, treat it as such as good practice to do because if you switch to PostgreSQL or MySQL, it will be an issue.

We can easily fix this by adjusting the timestamp prefix manually to place our roles before users or vice versa. So, instead of:

database/
└── migrations/
    ├── 1758943358073_create_users_table.ts
    └── 1770077349836_create_roles_table

We can instead do:

database/
└── migrations/
    ├── 1770077349836_create_roles_table.ts
    └── 1770077349837_create_users_table.ts

Noting that we've just taken our create_roles_table timestamp, incremented it by one and applied it as our create_users_table timestamp to change the natural sort.

Filling In Our Database

Great, so let's go ahead and run through a few more migrations to fill out the complete schema structure of our database, starting with a profile for our user.

node ace make:migration profiles
# DONE:    create database/migrations/1770079110036_create_profiles_table.ts

Within this migration, we'll want each row to be bound to a user, as this will be a one-to-one relationship. One user has one profile. Then, we'll also let them have a brief bio, giving this column a max size of 255 characters. Finally, adding a boolean to determine whether their profile is public or not. We can also default this to true.

// database/migrations/1770079110036_create_profiles_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'profiles'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.integer('user_id').unsigned().references('users.id').notNullable()
      table.string('bio', 255)
      table.boolean('is_public').defaultTo(true)

      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

Next, we'll have a challenges table.

node ace make:migration challenges
# DONE:    create database/migrations/1770079110048_create_challenges_table.ts

Inside of which, we'll note which user created the challenge, have text noting what the challenge is, and points noting a point value, the challenge is worth. This will be a many-to-one relationship. A user can have many challenge,s but a challenge can only be created by one user, which we'll use creator_id to track.

// database/migrations/1770079110048_create_challenges_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'challenges'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.integer('creator_id').unsigned().references('users.id').notNullable()
      table.string('text', 255).notNullable()
      table.integer('points').notNullable()

      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

Finally, we'll let users join a challenge via a challenge_user pivot table. Pivot tables allow us to join together many-to-many relationships. Users can join many challenges, and challenges have many users that've joined.

node ace make:migration challenge_user
# DONE:    create database/migrations/1770079119171_create_challenge_users_table.ts

Inside here, we'll first want to change the table name from plural to singular. The default naming convention Lucid will look for with pivot tables is a sorted concatenation of the two related entities in singular form. So, challenge comes before user when sorted, meaning the default would want challenge_user.

In addition to that, we want one column per joined entity along with a foreign key constraint. Finally, we can track when and if a user has completed the challenge in one go using a nullable timestamp. When null, the user hasn't completed the challenge, and when not null, then the user has completed the challenge, and we know when they've done so.

// database/migrations/1770079119171_create_challenge_users_table.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'challenge_user'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.integer('challenge_id').unsigned().references('challenges.id').notNullable()
      table.integer('user_id').unsigned().references('users.id').notNullable()

      table.timestamp('completed_at')
      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

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

Great, let's run our migrations!

node ace migration:run

Inspecting SQLite

You can either take my word for it that our tables are in our database, or we can see it for ourselves! Let's install a new extension in VS Code called SQLite Viewer. This will allow us to click on the SQLite database in our project to see its contents.

As mentioned earlier, our SQLite database is stored within the tmp directory, so let's open that up and give it a click, and we should now see a list of our tables.

If we make changes to our migrations, our database won't automatically be updated to match. Instead, we'd need to rollback and rerun the migration to apply whatever changes we've made. Once a migration has hit production, the flow changes. We should instead add a new migration to make whatever change we need because rolling back migrations in production is a destructive action and can lead to data loss.

Each middleware can:

• Pass the request to the next middleware by calling next()

• Modify the request before passing it along

• Modify the response coming back

• Stop the pipeline and return a response early

Creating Middleware

Let's create our own middleware to track how long requests take to process. We can use the make:middleware command to do this. When we run this command, it'll ask us which type of middleware we're creating.

• Server middleware will run for every request entering our application

• Router middleware will run for every request hitting a defined route in our application

• Named middleware will run only on routes where we specifically add them

node ace make:middleware request_logger
# ❯ Under which stack you want to register the middleware? · server
# DONE:    create app/middleware/request_logger_middleware.ts
# DONE:    update start/kernel.ts file

Let's select server for now. This will create a new middleware within app/middleware and register this as a new server middleware within our start/kernel.ts. The kernel file is responsible for registering middleware in our application.

Middleware Execution Flow

Our new middleware should look like the one below.

// app/middleware/request_logger_middleware.ts
import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class RequestLoggerMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    /**
     * Middleware logic goes here (before the next call)
     */
    console.log(ctx)

    /**
     * Call next method in the pipeline and return its output
     */
    const output = await next()
    return output
  }
}

As you can see, we have access to our HttpContext for the request here, just like in our controller methods. There is also a next() function as well. This next function is what instructs AdonisJS to move on from this middleware to the next one. When the route runs out of middleware, it'll move onto the route handler. Once the route handler is done, it'll work backwards through our middleware, running anything we've defined after the next() function, like a mountain pipeline.

├── Request
│   ├── Server Middleware (before next)
│   │   ├── Router Middleware (before next)
│   │   │   ├── Route Middleware (before next)
│   │   │   │   └── Route Handler
│   │   │   └── Route Middleware (after next)
│   │   └── Router Middleware (after next)
│   └── Server Middleware (after next)
└── Response

We can demonstrate this by tracking how long it takes to get from before next to after next!

// app/middleware/request_logger.ts
import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'
import { DateTime } from 'luxon'

export default class RequestLoggerMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    const start = DateTime.now()

    await next()

    const end = DateTime.now()
    const duration = end.diff(start).as('milliseconds').toFixed(2)

    ctx.logger.info(`[${ctx.request.method()}] ${ctx.request.url()} - ${duration} ms`)
  }
}

Our HttpContext also has access to a logger for our request. We can use this to print out an info message so that when we visit /challenges in our application, we should see something like:

INFO (89496): [GET] /challenges - 11.00 ms

Middleware Types

Since we have this as a server middleware, this will run even if we request a page that doesn't exist. So, if we request /not-found we'll see it still logs out.

INFO (89496): [GET] /not-found - 29.00 ms

Let's compare this to router middleware. If we jump into our start/kernel.ts file we'll see the below.

// start/kernel.ts
/*
|--------------------------------------------------------------------------
| HTTP kernel file
|--------------------------------------------------------------------------
|
| The HTTP kernel file is used to register the middleware with the server
| or the router.
|
*/

import router from '@adonisjs/core/services/router'
import server from '@adonisjs/core/services/server'

/**
 * The error handler is used to convert an exception
 * to an HTTP response.
 */
server.errorHandler(() => import('#exceptions/handler'))

/**
 * The server middleware stack runs middleware on all the HTTP
 * requests, even if there is no route registered for
 * the request URL.
 */
server.use([
  () => import('#middleware/container_bindings_middleware'),
  () => import('@adonisjs/static/static_middleware'),
  () => import('@adonisjs/vite/vite_middleware'),
  () => import('#middleware/request_logger_middleware')
])

/**
 * The router middleware stack runs middleware on all the HTTP
 * requests with a registered route.
 */
router.use([
  () => import('@adonisjs/core/bodyparser_middleware'),
  () => import('@adonisjs/session/session_middleware'),
  () => import('@adonisjs/shield/shield_middleware'),
  () => import('@adonisjs/auth/initialize_auth_middleware'),
  () => import('#middleware/silent_auth_middleware'),
])

/**
 * Named middleware collection must be explicitly assigned to
 * the routes or the routes group.
 */
export const middleware = router.named({
  guest: () => import('#middleware/guest_middleware'),
  auth: () => import('#middleware/auth_middleware'),
})

We've got our error handling middleware, server middleware, router middleware, and finally named middleware. Lazy-imports are how we register a middleware to a specific middleware type. So, if we move our request logger middleware from server.use to router.use it'll convert from being a server middleware to instead being a router middleware.

// start/kernel.ts
// ...

/**
 * The server middleware stack runs middleware on all the HTTP
 * requests, even if there is no route registered for
 * the request URL.
 */
server.use([
  () => import('#middleware/container_bindings_middleware'),
  () => import('@adonisjs/static/static_middleware'),
  () => import('@adonisjs/vite/vite_middleware'),
])

/**
 * The router middleware stack runs middleware on all the HTTP
 * requests with a registered route.
 */
router.use([
  () => import('@adonisjs/core/bodyparser_middleware'),
  () => import('@adonisjs/session/session_middleware'),
  () => import('@adonisjs/shield/shield_middleware'),
  () => import('@adonisjs/auth/initialize_auth_middleware'),
  () => import('#middleware/silent_auth_middleware'),
++  () => import('#middleware/request_logger_middleware'),
])

// ...

If we request /not-found one more time, we'll notice we no longer get a log of our request time. However, if we request /challenges again, our request time log goes through just fine, verifying that server middleware runs for any request and router middleware only runs for registered routes. Note, server and router middleware are executed in the order they're imported here.

Finally, if we move this from router.use down to our router.named we'll switch this to a named middleware, so we also need to give it a name.

// start/kernel.ts
// ...

/**
 * The router middleware stack runs middleware on all the HTTP
 * requests with a registered route.
 */
router.use([
  () => import('@adonisjs/core/bodyparser_middleware'),
  () => import('@adonisjs/session/session_middleware'),
  () => import('@adonisjs/shield/shield_middleware'),
  () => import('@adonisjs/auth/initialize_auth_middleware'),
  () => import('#middleware/silent_auth_middleware'),
])

/**
 * Named middleware collection must be explicitly assigned to
 * the routes or the routes group.
 */
export const middleware = router.named({
  guest: () => import('#middleware/guest_middleware'),
  auth: () => import('#middleware/auth_middleware'),
  requestLogger: () => import('#middleware/request_logger_middleware'),
})

If we request /challenges again, note we no longer get a log. This is because named middleware only runs on routes we've specifically added the middleware to. So, we need to first add requestLogger to challenges.index in order for it to log.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

// ...

++router.get('/challenges', [controllers.Challenges, 'index']).use(middleware.requestLogger())
router.get('/challenges/:id', [controllers.Challenges, 'show'])
router.get('/challenges/create', [controllers.Challenges, 'create'])
router.post('/challenges', [controllers.Challenges, 'store'])
router.get('/challenges/:id/edit', [controllers.Challenges, 'edit'])
router.put('/challenges/:id', [controllers.Challenges, 'update'])

// ...

Request /challenges one more time, and voila! There's our log again.

Middleware & Route Groups

The use method accepts one or more middleware we want to define on the specific route or route group. Anything we add to route groups gets applied to all routes within the group. So, we could wrap our challenges in a group to easily apply this middleware to all these routes in one go.

// start/routes.ts
// ...

router
  .group(() => {
    router.get('/challenges', [controllers.Challenges, 'index'])
    router.get('/challenges/:id', [controllers.Challenges, 'show'])
    router.get('/challenges/create', [controllers.Challenges, 'create'])
    router.post('/challenges', [controllers.Challenges, 'store'])
    router.get('/challenges/:id/edit', [controllers.Challenges, 'edit'])
    router.put('/challenges/:id', [controllers.Challenges, 'update'])
  })
  .use(middleware.requestLogger())

// ...

We can take this a step further as well and move /challenges to the group-level as well if we wish. This works for names, domains, and matchers as well.

// start/routes.ts
// ...

router
  .group(() => {
    router.get('/', [controllers.Challenges, 'index'])
    router.get('/:id', [controllers.Challenges, 'show'])
    router.get('/create', [controllers.Challenges, 'create'])
    router.post('/', [controllers.Challenges, 'store'])
    router.get('/:id/edit', [controllers.Challenges, 'edit'])
    router.put('/:id', [controllers.Challenges, 'update'])
  })
  .prefix('/challenges')
  .use(middleware.requestLogger())

// ...

Middleware & Resources

Okay, I think we're ready to condense this down to a simple resource route definition. Again, this takes the shared pattern (/challenges) and the controller and AdonisJS will do the rest.

// start/routes.ts
// ...

router.resource('challenges', controllers.Challenges).use('*', middleware.requestLogger())

// ...

Note that here use requires two arguments. In the first, we specify which route in the resource to target, * will target them all. Then, we provide the middleware. The first argument can also be an array of routes as well.

// start/routes.ts
// ...

router
  .resource('challenges', controllers.Challenges)
  .use(['index', 'edit', 'create'], middleware.requestLogger())

// ...

Prematurely Ending A Request

Finally, we can prematurely stop a request in its tracks with middleware as well by returning a response before the next method.

// app/middleware/request_logger_middleware.ts
import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'
import { DateTime } from 'luxon'

export default class RequestLoggerMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
++    if (ctx.request.input('bail')) {
++      return ctx.response.json({ message: 'Bailed out!' })
++    }

    const start = DateTime.now()

    await next()

    const end = DateTime.now()
    const duration = end.diff(start).as('milliseconds').toFixed(2)

    ctx.logger.info(`[${ctx.request.method()}] ${ctx.request.url()} - ${duration} ms`)
  }
}

the input method on our request will attempt to find the key provided in either our request body or query string. So, if we request /challenges?bail=true then we'll get our "Bailed out!" message. If we omit the bail query param, our request will go on as usual!

When a user first visits your site, AdonisJS creates a session for them and stores a session ID in a cookie. On subsequent requests, the browser sends this cookie, allowing AdonisJS to retrieve the session data associated with that user.

Request 1 → Create Session → Set Cookie → Response
Request 2 → Read Cookie → Retrieve Session → Response
Request 3 → Read Cookie → Retrieve Session → Response

Setting Setting State

Sessions are ephemeral by default; they exist for the duration of the user's visit and can be cleared when the browser closes (depending on configuration).

You can set data on a session using the session.put() method within your controller:

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class ChallengesController {
  // ...
  
  async store({ request, response, session }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)

    challenges.push({ id: challenges.length + 1, ...data })

++    session.put('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  //...
}

The session.put() method takes a key and a value. You can store primitives like strings and numbers, objects, or even arrays.

Accessing Session State

Session data can then be accessed throughout your request and views via the HttpContext. Within our controllers and middleware, we can use session.get().

// app/controllers/challenges_controller.ts
async index({ session, view }: HttpContext) {
  const successMessage = session.get('success')
  
  return view.render('pages/challenges/index', { 
    challenges,
    successMessage 
  })
}

We don't need to access our session within controllers though, session is also made directly available as an EdgeJS global, allowing easy access to a similar API within our views. One key note, though, is that the session in our views is a read-only store. Meaning, we can't alter the store with it.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
++    @if (session.has('success'))
++      <div class="alert alert-success">
++        {{ session.get('success') }}
++      </div>
++    @endif
    
    <div class="hero">
      <h1>Challenges</h1>
  
      @include('partials/challenge/available_points')
  
      <a href="{{ route('challenges.create') }}" class="button">Create a new challenge</a>
    </div>

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
  </div>

@end

Now, there's an issue with what we just did. If we refresh our page, our session is still signalling that we've just created a challenge because the message is persisted in our session for the duration of our session or until we instruct our session to forget it.

What Are Flash Messages?

Flash messages are a special type of session data in that they only last for a single request. This makes them perfect for one-time notifications like what we have above. Unlike session.put(), where the data persists until you manually delete it, when we use session.flash(), the data is automatically forgotten on the next request.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class ChallengesController {
  // ...
  
  async store({ request, response, session }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)

    challenges.push({ id: challenges.length + 1, ...data })

++    session.flash('success', 'Challenge created successfully')

    return response.redirect().toRoute('challenges.index')
  }

  //...
}

If you'll recall back to our lesson on validation, flash messaging is how request validations provide errors and old form data to us. In that, we learned we can access flash messages using flashMessages.get('success'), which would return our message. Since we're familiar, let's jump straight in because the starter kit is already set up to show our success flash message!

Let's remind ourselves of our layout:

// resources/views/components/layout.edge
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>
      AdonisJS - A fully featured web framework for Node.js
    </title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @stack('dumper')
  </head>
  <body>
    @include('partials/header')
    <main>
++      @include('partials/flash_alerts')
      {{{ await $slots.main() }}}
    </main>
  </body>
</html>

Note the flash_alerts partial! If we check out this partial next:

// resources/views/partials/flash_alerts.edge
<div class="flash-container">
  @if(flashMessages.has('error'))
    @alert.root({ variant: 'destructive', autoDismiss: true })
      @!alert.description({ text: flashMessages.get('error') })
    @end
  @end
  @if(flashMessages.has('success'))
    @alert.root({ variant: 'success', autoDismiss: true })
      @!alert.description({ text: flashMessages.get('success') })
    @end
  @end
</div>

We'll see that it's checking to see if our flash message store has an "error" or "success" value. If so, it's using alert components to render out the flash message on our page! So, let's check it out and give our page a refresh.

Hmm... nothing changed. Ah! Because we never instructed our session to forget our previous success value.

Forgetting Session State

Forgetting state in our session is pretty straightforward; we just need to call session.forget() from our HttpContext (remember it's read-only in our views) and provide the key we want to forget. We could also use session.clear() to remove all data from our session.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  async index({ session, view }: HttpContext) {
++    session.forget('success')
    
    return view.render('pages/challenges/index', { challenges })
  }
}

Now, if we refresh once more, our success message should be gone. Okay, we don't need that anymore, let's remove it.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  async index({ view }: HttpContext) {
    return view.render('pages/challenges/index', { challenges })
  }
}

Great, let's create a new challenge really quickly. When we do, we should see our success flash message display. However, this time, if we refresh, our flash message should be gone and won't display again until another challenge is created. Perfect!

Small note, you may find yourself in a situation where you need to keep your flash messages for one more request. This can be easily done using session.reflash(). There's also session.reflashOnly() and session.reflashExcept() to include or omit specific keys.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  async index({ session, view }: HttpContext) {
++    session.reflash()

    return view.render('pages/challenges/index', { challenges })
  }
}

With this added, now if we create a new challenge, we'll get redirected to our index page. Our index page will reflash it's flash messages, meaning they'll be kept for one more request. So, if we refresh our page, we'll see our success message yet again. This is particularly handy when handling errors manually!

Defining Validators

To start, we'll make a new file for our challenge validator using the Ace CLI.

node ace make:validator challenge
# DONE:    create app/validators/challenge.ts

We can find our validator files within app/validators and a single file can define and export multiple validators. When we open our new challenge validator file, we'll find an import for VineJS. VineJS is AdonisJS's validation system; like EdgeJS, it too is home-grown by the AdonisJS Core Team.

// app/validators/challenge.ts
import vine from '@vinejs/vine'

We define a validator by calling the create method from vine and pass in an object where the keys are the field names we're submitting with our form. The values of our object are then the validation rules for that field.

// app/validators/challenge.ts
import vine from '@vinejs/vine'

++export const challengeValidator = vine.create({
++  text: vine.string().minLength(5).maxLength(255),
++  points: vine.number().min(1).max(100),
++})

We start by describing the type of the field, our text is a string, and points is a number. Then, we can add additional constraints or normalizations we want the field to adhere to. Here, we're saying the text value must be between 5 and 255 characters long, and the points value must be between 1 and 100. Alternatively, we could use range([1, 100]) to do the same.

By default, any field we define in our validator will be required, unless specifically marked as optional(). In our case, we need both of these fields for our challenge, so we'll keep them both as required.

Validating Data

Next, we need to use our validator within our controller.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response }: HttpContext) {
++    const data = await request.validateUsing(challengeValidator)

    challenges.push({ id: challenges.length + 1, ...data })

    return response.redirect('/challenges')
  }

  // ...

  /**
   * Handle form submission for the edit action
   */
  async update({ params, request, response }: HttpContext) {
++    const data = await request.validateUsing(challengeValidator)

    // find the challenge being updated by its id, and update its data
    const challengeIndex = challenges.findIndex((row) => row.id === params.id)
    challenges[challengeIndex] = { id: params.id, ...data }

    return response.redirect('/challenges')
  }

  // ...
}

By using the validator directly off our request, AdonisJS will automatically pass our request's data, including the body, route params, query strings, cookies, and headers, to the validator. The request body is a direct property, while everything else is nested under their applicable name, for example:

// example
import vine from '@vinejs/vine'

export const exampleValidator = vine.create({
  someBodyProperty: vine.string(),

  params: vine.object({
    id: vine.number()
  }),

  qs: vine.object({
    sort: vine.string().in(['asc', 'desc']),
  }),

  cookies: vine.object({
    sessionId: vine.string()
  }),

  headers: vine.object({
    'x-api-version': vine.number().range([1, 7])
  })
})

Additionally, the data we get back from our validation is type-safe as well. If, for any reason, we need to use a validator's type, we can easily do so with VineJS's Infer type helper.

import { type Infer } from '@vinejs/vine/types'

function example({ text, points }: Infer<typeof challengeValidator>) {
  console.log({ text, points })
}

Our challengeValidator will give us our object type:

const data: {
  text: string;
  points: number;
}

Finally, if we need to explicitly define the data that should be validated, we can do that as well using the validator directly.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response }: HttpContext) {
++    const data = await challengeValidator.validate(request.all())

    challenges.push({ id: challenges.length + 1, ...data })

    return response.redirect('/challenges')
  }

  // ...
}

Validation Errors & User Feedback

Okay, so let's give our validator a try by entering something like:

{
  "text": "test",
  "points": 500
}

When we send this, you'll notice we get redirected right back to where we were, and our form is emptied, why? When our validation fails, the validator will throw an exception. Our exception handler will then conveniently handle this for us using content-negotiation. When we submit an HTML form, it will redirect us back to the page. When using application/json it will return a 422 status code with our errors. So, where can we find our errors for form submissions?

Let's dump our state, and fill out our form again with a text of "test" and "500" points, and submit again.

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

++    @dump(state)

    {{-- ... --}}
  </div>

@end

On our state we should see a property called flashMessages. Flash messages are messages sent by our server for this single request. If we expand this, we should see the following.

flashMessages: ReadOnlyValuesStore {
  values: Object {
    text: 'test',
    points: '500',
    errorsBag: Object {
      E_VALIDATION_ERROR: 'The form could not be saved. Please check the errors below.',
    },
    inputErrorsBag: Object {
      text: Array:1 [
        'The text field must have at least 5 characters',
      ],
      points: Array:1 [
        'The points field must be between 1 and 100',
      ],
    },
  },
  [[Prototype]] {}
}

This is where we can find the contextual information about our validation failure. The errorsBag is where we'll find general exceptions and errors and inputErrorsBag is where we'll find specific validation errors. If there is a property in here, it means that the field failed validation, and AdonisJS gives an array of messages for those failures. Additionally, you'll also note AdonisJS has flashed the text and point values we submitted as well.

So, how can we use all of this? Well, for starters, we can access them directly with our flashMessages directly, or using one of its helper methods listed in its prototype.

flashMessages: ReadOnlyValuesStore {
  values: Object {...},
  [[Prototype]] {
    isEmpty: [Getter]
    get: [function get],
    has: [function has],
    all: [function all],
    toObject: [function toObject],
    toJSON: [function toJSON],
  }
}

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    @dump(state)

    <div>
      <form action="/challenges" method="POST">
        {{ csrfField() }}

        <div>
          <label>
            Text
            <input type="text" name="text" />
          </label>

++          @if (flashMessages.has('inputErrorsBag.text'))
++            <div>
++              {{ flashMessages.get('inputErrorsBag.text').join(', ') }}
++            </div>
++          @endif
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" />
          </label>

++          @if (flashMessages.has('inputErrorsBag.points'))
++            <div>
++              {{ flashMessages.get('inputErrorsBag.points').join(', ') }}
++            </div>
++          @endif
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

This is a common situation, though, so AdonisJS has added some utility tags to help us get at this data called @inputError. This tag injects our errors into the main scope, so we can access them with just $messages.

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    @dump(state)

    <div>
      <form action="/challenges" method="POST">
        {{ csrfField() }}

        <div>
          <label>
            Text
            <input type="text" name="text" />
          </label>

++          @inputError('text')
++            <div>
++              {{ $messages.join(', ') }}
++            </div>
++          @end
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" />
          </label>

++          @inputError('points')
++            <div>
++              {{ $messages.join(', ') }}
++            </div>
++          @end
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Fantastic! Same situation if we'd like to repopulate our form with its previously submitted values, which is generally a good idea. Again, this is a common situation, so there's a utility method called old() to help us get at this as well.

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    @dump(state)

    <div>
      <form action="/challenges" method="POST">
        {{ csrfField() }}

        <div>
          <label>
            Text
++            <input type="text" name="text" value="{{ flashMessages.get('text', '') }}" />
          </label>

          @inputError('text')
            <div>
              {{ $messages.join(', ') }}
            </div>
          @end
        </div>

        <div>
          <label>
            Points
++            <input type="number" name="points" value="{{ old('points') }}" />
          </label>

          @inputError('points')
            <div>
              {{ $messages.join(', ') }}
            </div>
          @end
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Cleaning Up with Components

Great, our form is looking good! Let's make it look better, because the starter kit comes with components, wrapping everything we've done here in a pretty little bow!

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      <form action="/challenges" method="POST">
        {{ csrfField() }}

        <div>
++          @field.root({ name: 'text' })
++            @!field.label({ text: 'Text' })
++            @!input.control({ type: 'text' })
++            @!field.error()
++          @end
        </div>

        <div>
++          @field.root({ name: 'points' })
++            @!field.label({ text: 'Points' })
++            @!input.control({ type: 'number' })
++            @!field.error()
++          @end
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Here, @field.root({ name: 'text' }) injects the previously submitted value and validation errors into its child context. The control and error then read that context to display things similarly to how we just had it ourselves, giving you an idea of just how powerful components can be at condensing things into an easily digestible package.

The only thing these components use that we haven't already covered are prop helpers! If we, for example, take a look at our field label component.

// resources/views/components/field/label.edge
@let(labelTextFromSlot = await $slots.main())
@let(labelText = labelTextFromSlot.trim() ? labelTextFromSlot : $props.get('text'))
@let(classes = [])

<label {{ $props
  .except(['text'])
  .merge({
    for: $context.id,
    class: classes,
    'data-invalid': $context.hasErrors ? 'true' : false,
  })
  .toAttrs() }}>{{{ labelText }}}</label>

First, it's putting its slot's HTML into a variable called labelTextFromSlot. If it has contents, it'll use that as the value for labelText, otherwise it will try to get the text prop using the $props get method utility.

We've seen these methods before when we took a look at $props prototype methods:

ComponentProps {
  [[Prototype]] {
    all: [function all],
    has: [function has],
    get: [function get],
    only: [function only],
    except: [function except],
    merge: [function merge],
    mergeIf: [function mergeIf],
    mergeUnless: [function mergeUnless],
    toAttrs: [function toAttrs],
  }
}

Our label is stating that it wants to use all the props except text. Merge for, class, and data-invalid into those props. Finally, toAttrs() takes the chain's results and converts them into valid HTML attributes to be placed on the label.

Sweet, before we round out this lesson, let's get our edit page up-to-date as well.

// resources/views/pages/challenges/edit.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Edit Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      <form action="/challenges/{{ challenge.id }}?_method=PUT" method="POST">
        {{ csrfField() }}

        <div>
          @field.root({ name: 'text' })
            @!field.label({ text: 'Text' })
            @!input.control({ type: 'text', value: challenge.text })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'points' })
            @!field.label({ text: 'Points' })
            @!input.control({ type: 'number', value: challenge.points })
            @!field.error()
          @end
        </div>

        <div>
          <button type="submit" class="button"> Update Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Remember, we need to pre-populate the field's values with the values of the challenge we're editing. Like our label component, the input control component will also build out and merge its props into attributes, so value works just fine here!

• Partials, reusable fragments that share the same state as their parent

• Components, reusable fragments with isolated state, props, and slots

Partials

Partials are straightforward, reusable bits of markup that share the same state as their parent. They behave as though the markup written inside them was written directly in the parent, just with the bonus of reusability.

They can, however, also be used to keep things clean as well. So, let's add a partial to extract our availablePoints aggregation out of our page to clean this up a little bit.

node ace make:view partials/challenge/available_points
# DONE:    create resources/views/partials/challenge/available_points.edge

// resources/views/partials/challenge/available_points.edge
@let(availablePoints = challenges.reduce((total, challenge) => total + challenge.points, 0))

@if (completedChallenges?.length)
  @let(completedPoints = completedChallenges.reduce((total, challenge) => total + challenge.points, 0))
  @assign(availablePoints = availablePoints - completedPoints)
@endif

<div>
  Total Points Available: {{ availablePoints }}
</div>

Since this shares the same state as its parent, we can openly use our challenges state available on our page. Next, we need to include this partial in our page. For that, there's a special @include tag that accepts the path to our desired partial. Again, AdonisJS already knows to look within resources/views so that should be omitted. Additionally, the @partial tag is self-closing, meaning we do not need to @end it.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

++    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    <ul>
      @each(challenge in challenges)
        <li>
          <a href="/challenges/{{ challenge.id }}">
            <h3>{{ challenge.text }}</h3>
            <p>Points: {{ challenge.points }}</p>
          </a>
        </li>
      @endeach
    </ul>
  </div>

@end

With that, our page should render the same as before, with the bonus of cleanliness in our page!

Components

Now, unlike partials, components don't share state, but instead have their own isolated state. Meaning, if we wanted to access challenges from our page, we would need to pass it into the component via what's called props. The props we pass into the component are then merged into the isolated state of the component and made available for use. Components do, however, still have access to global and local state!

For this, let's focus on our unordered list by creating a new challenge_grid component.

node ace make:view components/challenge/grid
# DONE:    create resources/views/components/challenge/grid.edge

Next, let's move our unordered list into this component.

// resources/views/components/challenge/grid.edge
<ul>
  @each(challenge in challenges)
    <li>
      <a href="/challenges/{{ challenge.id }}">
        <h3>{{ challenge.text }}</h3>
        <p>Points: {{ challenge.points }}</p>
      </a>
    </li>
  @endeach
</ul>

Components can be used similarly to partials via a designated @component() tag. This also takes a path to the component from resources/views.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

++    @component('components/challenge/grid')
++    @endcomponent
  </div>

@end

Note, unlike partials, components must be ended. More on the reason why in a minute.

Component Props

Since components have an isolated state, we have to pass the data from our page that we want it to have access to as a prop, which can be done via an object as the second argument.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

++    @component('components/challenge/grid', { challenges })
    @endcomponent
  </div>

@end

With that, our component now has access to challenges from the render state of our page and can successfully render out our unordered list! Now, although our component props are merged into the state, we can directly access props as well via $props should we need to. Let's dump this out and take a look!

// resources/views/components/challenge/grid.edge
<ul>
  @each(challenge in challenges)
    <li>
      <a href="/challenge/{{ challenge .id }}">
        <h3>{{ challenge.text }}</h3>
        <p>Points: {{ challenge.points }}</p>
      </a>
    </li>
  @endeach
</ul>

++@dump($props)

From our dump, we can see this is a ComponentProps object-like structure. Our challenges is a key on this with our array within it, but if we dig into the prototype, we can see this has some utility methods on it as well to get all props, specific props, and more.

ComponentProps {
  challenges: Array:3 [],
  [[Prototype]] {
    all: [function all],
    has: [function has],
    get: [function get],
    only: [function only],
    except: [function except],
    merge: [function merge],
    mergeIf: [function mergeIf],
    mergeUnless: [function mergeUnless],
    toAttrs: [function toAttrs],
  }
}

Okay, we can remove that dump, and let's alter our markup here slightly, removing our unordered list and adding a cards class that came with the starter kit. This will display our challenges in a grid with three columns.

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
    <a href="/challenges/{{ challenge.id }}">
      <h3>{{ challenge.text }}</h3>
      <p>Points: {{ challenge.points }}</p>
    </a>
  @endeach
</div>

Next, let's add another component that will be in charge of rendering each challenge within our grid.

node ace make:view components/challenge/grid_item
# DONE:    create resources/views/components/challenge/grid_item.edge

We'll move the div from inside our loop into this new component.

// resources/views/components/challenge/grid_item.edge
<a href="/challenges/{{ challenge.id }}">
  <h3>{{ challenge.text }}</h3>
  <p>Points: {{ challenge.points }}</p>
</a>

Then, let's add this component within our loop and pass each challenge into it as a prop.

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
++    @component('components/challenge/grid_item', { challenge })
++    @endcomponent
  @endeach
</div>

Component Slots

A couple of things here. Although the component tag is not self-closing, we can mark it as such by using an exclamation point, like @!component(). With this, we no longer need an @end, so we can remove it.

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
++    @!component('components/challenge/grid_item', { challenge })
  @endeach
</div>

Why aren't components self-closing? Because they can utilize slots or child content. We can register a position inside our component for where child contents should go!

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
++    {{{ await $slots.main() }}}
  @endeach
</div>

Here, $slots is an object that gets named slots we can utilize within our component. The main slot is the default slot and will always be defined. If this looks familiar, it's because we saw exactly this within our layout! Next, we place our grid item as child content, between the start and end tags, within our grid component, within our index page.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    @component('components/challenge/grid', { challenges })
++      @!component('components/challenge/grid_item')
    @endcomponent
  </div>

@end

Slot Scopes

The problem here is that we need access to our individual challenge being looped over for our grid item. One option we have is to use slot scopes. This is contextual information we can pass through the slot, via an argument to the slot method, to the child.

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
++    {{{ await $slots.main({ challenge }) }}}
  @endeach
</div>

Then, we can use the @slot tag to access this scope for the child.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    @component('components/challenge/grid', { challenges })
++      @slot('main', scope)
++        @!component('components/challenge/grid_item', { challenge: scope.challenge })
++      @endslot
    @endcomponent
  </div>

@end

Injected State

We could alternatively skip the middleman, though, and inject the challenge directly from the grid component into the child grid item component.

// resources/views/components/challenge/grid.edge
<div class="cards">
  @each(challenge in challenges)
++    @inject({ challenge })
    {{{ await $slots.main() }}}
  @endeach
</div>

This injects our challenge into the $context of the child contents for this component. We can then access this $context directly inside our grid item component for use. Since the inject and slot occur for each loop, this will happen once per individual item in our array.

// resources/views/components/challenge/grid_item.edge

++@let(challenge = $context.challenge)
<a href="/challenges/{{ challenge.id }}">
  <h3>{{ challenge.text }}</h3>
  <p>Points: {{ challenge.points }}</p>
</a>

Lastly, we need to remove the middleman from our index page. If we dump the $context from our index page, it'll make a little more evident exactly what's happening here as well.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    @component('components/challenge/grid', { challenges })
++      @dump($context)
++      @!component('components/challenge/grid_item')
    @endcomponent
  </div>

@end

As you can see, we get three individual dumps, one per item we're looping over! Great, we can remove that dump. The last, and probably cleanest, option is to just loop directly within our page.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

++    @component('components/challenge/grid')
++      @each(challenge in challenges)
++        @!component('components/challenge/grid_item', { challenge })
++      @endeach
++    @endcomponent
  </div>

@end

// resources/views/components/challenge/grid.edge
<div class="cards">
  {{{ await $slots.main() }}}
</div>

// resources/views/components/challenge/grid_item.edge
<a href="/challenges/{{ challenge.id }}">
  <h3>{{ challenge.text }}</h3>
  <p>Points: {{ challenge.points }}</p>
</a>

Component Tags

Next, any component created within the resources/views/components folder automatically gets registered as a tag and can be used as such. This gives us a more convenient way to utilize components and cleaner markup to boot. Imagine the folder structure of the component file as a camel-cased nested JavaScript object. So, challenge/grid_item would be:

const challenge = {
  grid: '...',
  gridItem: '...'
}

challenge.grid
challenge.gridItem

That is how we can access the component in tag form! Importantly, note that component tags do not have a corresponding named end tag to go with them. So here, we will just want to use @end to end the component.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    @include('partials/challenge/available_points')

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

++    @challenge.grid()
++      @each(challenge in challenges)
++        @!challenge.gridItem({ challenge })
++      @endeach
++    @end
  </div>

@end

Now, if you're thinking, hey this looks familiar, you're right! What we've just done is exactly how our layout works because the layout itself is a component. If you want to add another layout option, you can create a new component just like we have here.

Small note, if you have a component at resources/views/components/challenge/index.edge, you can access it as a tag with just @challenge(). The index will be implied if omitted!

Making A Create Page

First, we'll need a page, and if you'll recall back to our resourceful naming, convention states this should be /challenges/create.

node ace make:view pages/challenges/create
# DONE:    create resources/views/pages/challenges/create.edge

// start/routes.ts
// ...

router.get('/challenges', [controllers.Challenges, 'index'])
router.get('/challenges/:id', [controllers.Challenges, 'show'])
++router.get('/challenges/create', [controllers.Challenges, 'create'])

// ...

Within the create method of our challenges controller, we'll render our new create page.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Display form to create a new record
   */
++  async create({ view }: HttpContext) {
++    return view.render('pages/challenges/create')
++  }

  // ...
}

Let's add a link for ourselves on our challenges page to point to this form. While we're here, we can clean this up a little as well.

@layout()

  <div>
    <div class="hero">
      <h1>Challenges</h1>
  
      @include('partials/challenge/available_points')
  
      <a href="/challenges/create" class="button">Create a new challenge</a>
    </div>

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
  </div>

@end

Basic Form Submissions

Okay, great! Now onto our create page. Here we'll want a form with the fields our challenge requires.

• text for the name of the challenge

• points for the points our users get for completing the challenge

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      <form action="/challenges" method="POST">
        <div>
          <label>
            Text
            <input type="text" name="text" />
          </label>
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" />
          </label>
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Again, keeping with our resourceful naming, to store new records, we should send a POST request to /challenges. So, let's create that route next.

// start/routes.ts
// ...

router.get('/challenges', [controllers.Challenges, 'index'])
router.get('/challenges/:id', [controllers.Challenges, 'show'])
router.get('/challenges/create', [controllers.Challenges, 'create'])
router.post('/challenges', [controllers.Challenges, 'store'])

// ...

Next, for our controller, when we submit our form, the data within it will be sent up within our request's body. There are numerous ways we can get body data from our request. With request.all() it will simply return everything. Let's take a peek at what we're getting first.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
++  async store({ request }: HttpContext) {
++    const data = request.all()
++    console.log({ data })
++  }

  // ...
}

Cross-Site Request Forgery

If we stop, fill out our form, and hit submit. You'll notice our browser refreshes and the form clears out. Let's check our server's log to see what we got!

WARN (21151): Invalid or expired CSRF token
request_id: "fac1d913-f3a0-40d8-8da0-89996276225b"
x-request-id: "fac1d913-f3a0-40d8-8da0-89996276225b"

What you'll find is a warning that the server recieved an "invalid or expired CSRF token," what's this about? CSRF stands for Cross-Site Request Forgery, and per OWASP:

"Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they’re currently authenticated. With a little help of social engineering (such as sending a link via email or chat), an attacker may trick the users of a web application into executing actions of the attacker’s choosing"

• OWASP - https://owasp.org/www-community/attacks/csrf

To protect against this, our server generates a token with every request. When we submit POST, PUT, PATCH, or DELETE requests from our application, it will expect that token to be sent along with that request as verification that the request originated from our site, as a way to protect against these malicious attacks. This token is referred to as the CSRF Token, and AdonisJS provides a utility method, csrfField() we can call to plop a CSRF token field into our forms.

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      <form action="/challenges" method="POST">
++        {{ csrfField() }}

        <div>
          <label>
            Text
            <input type="text" name="text" />
          </label>
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" />
          </label>
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Perfect! Let's try our form one more time. This time, you'll notice we get a blank page after we submit. This is because we aren't sending anything back as a response; we'll change that in a moment. First, though, let's check our log.

{
  data: {
    _csrf: '6ysucdLo-pdCD18tWTyeS8qRubQarXYs13BQ',
    text: 'Test',
    points: '10'
  }
}

Awesome, this time we got our body data, and we can even see our CSRF token coming through to boot.

Picking Body Data

Now, it is never a good idea to take in any data the user sends. Always be defensive when it comes to the data your application accepts from users. So, instead of using request.all() we can switch this to only accept the properties we expect. For this, again, we have a couple of options.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request }: HttpContext) {
++    const data = request.only(['text', 'points'])
++    const text = request.input('text')
++    const points = request.input('points')
++    console.log({ data, text, points })
  }

  // ...
}

I want to note, though this is more defensive than using request.all() even these aren't ideal. We'll always want to validate user data. We'll cover that in the next lesson, so don't brush your hands off thinking you're done here.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response }: HttpContext) {
    const data = request.only(['text', 'points'])
    
++    challenges.push({ id: challenges.length + 1, ...data })
  }

  // ...
}

Typically, we would take in data and store it within a database for long-term storage. We aren't there yet, so we'll work with what we have at the moment, which is our in-memory array. Note, since it's in-memory, anything we add or remove to it will be undone when we restart our server, as that destroys the memory. So, let's pick our text and points values off our request and push them as a new challenge into our challenges array. We'll also assign it an incremented ID.

Handling Form Responses

So that we aren't met with a blank page again, we can forward our user back to the challenges page so we can see our updated list.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Handle form submission for the create action
   */
  async store({ request, response }: HttpContext) {
    const data = request.only(['text', 'points'])
    
    challenges.push({ id: challenges.length + 1, ...data })

++    return response.redirect('/challenges')
  }

  // ...
}

Responses are how we send instructions and data from our server back to the user. On our response, in our HttpContext is a redirect() method. This will alter our response to a 302, redirect status code with the Location header set to the path we've specified. The browser will take these instructions and use them to redirect the user to the challenges page.

Now, if we submit our form, not only will we be redirected, but we'll also see our new challenge added to our list!

Editing Data with a Form

Next, let's add the ability to edit a challenge by first getting our edit page created.

node ace make:view pages/challenges/edit
# DONE:    create resources/views/pages/challenges/edit.edge

Then, we'll add two routes:

• GET: /challenges/:id/edit to render the edit form

• PUT: /challenges/:id to handle the updating

// start/routes.ts
// ...

router.get('/challenges', [controllers.Challenges, 'index'])
router.get('/challenges/:id', [controllers.Challenges, 'show'])
router.get('/challenges/create', [controllers.Challenges, 'create'])
router.post('/challenges', [controllers.Challenges, 'store'])
++router.get('/challenges/:id/edit', [controllers.Challenges, 'edit'])
++router.put('/challenges/:id', [controllers.Challenges, 'update'])

// ...

Next, we'll render our edit form within the edit method of our controller and update the challenge with the submitted data in our update method.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  // ...

  /**
   * Edit individual record
   */
  async edit({ params, view }: HttpContext) {
    // find the challenge being edited by its id
    const challenge = challenges.find((row) => row.id === params.id)

    // pass the challenge to the view
    return view.render('pages/challenges/edit', { challenge })
  }

  /**
   * Handle form submission for the edit action
   */
  async update({ params, request, response }: HttpContext) {
    const data = request.only(['text', 'points'])

    // find the challenge being updated by its id, and update its data
    const challengeIndex = challenges.findIndex((row) => row.id === params.id)
    challenges[challengeIndex] = { id: params.id, ...data }

    return response.redirect('/challenges')
  }

  // ...
}

We then need to fill out our page. We can copy/paste our create page as a starting point, updating "create" to "edit." We also need to pre-populate the field's values with the values of the challenge we're editing. Finally, we need to update our form's action to point to the specific challenge ID we're looking to update.

// resources/views/pages/challenges/edit.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Edit Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      <form action="/challenges/{{ challenge.id }}" method="POST">
        {{ csrfField() }}

        <div>
          <label>
            Text
            <input type="text" name="text" value="{{ challenge.text }}" />
          </label>
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" value="{{ challenge.points }}" />
          </label>
        </div>

        <div>
          <button type="submit" class="button"> Update Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

And, let's give ourselves a link to this page from our challenge's show page. I'm also going to add our "hero" class to our div as well.

// resources/views/pages/challenges/show.edge
@layout()

  <div class="hero">
    <h1>{{ challenge.text }}</h1>
    <p>Points: {{ challenge.points }}</p>

    <a href="/challenges/{{ challenge.id }}/edit" class="button">Edit Challenge</a>
  </div>

@end

HTTP Method Spoofing

If we now go to update one of our challenges, you'll notice we're met with a 404 exception.

Cannot POST:/challenges/1

The keyword of note here is "POST". We've defined this route using resourceful conventions, so its HTTP Verb is PUT and not POST. So, how do we fix this? Your first thought might be to switch the method="POST" attribute on our form to method="PUT" and that'd be fantastic, if browsers supported that. Unfortunately, they only support GET and POST as form methods. Instead, we need to use HTTP Method Spoofing. This allows us to send our request from the form as a POST but have our server understand it as a PUT, PATCH, or DELETE instead.

In AdonisJS 7, this is enabled by default, but just in case, you can find this within your config/app.ts file.

// config/app.ts
/**
 * The configuration settings used by the HTTP server
 */
export const http = defineConfig({
  // ...

  /**
   * Allow method spoofing via _method query parameter or form field.
   * Enables using PUT, PATCH, DELETE methods in HTML forms by spoofing
   * through POST requests with _method field.
   */
  allowMethodSpoofing: true,

  // ...
})

As noted here, to use it, all we need to do is include a _method=PUT query string on our form action's URL.

// resources/views/pages/challenges/edit.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Edit Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
++      <form action="/challenges/{{ challenge.id }}?_method=PUT" method="POST">
        {{ csrfField() }}

        <div>
          <label>
            Text
            <input type="text" name="text" value="{{ challenge.text }}" />
          </label>
        </div>

        <div>
          <label>
            Points
            <input type="number" name="points" value="{{ challenge.points }}" />
          </label>
        </div>

        <div>
          <button type="submit" class="button"> Update Challenge </button>
        </div>
      </form>
    </div>
  </div>

@end

Now, if we attempt to update a challenge once more... voila! All works according to plan.

Naming Routes

When we define routes, we can assign them a name by chaining an as() method on the route definition. We've actually already seen this with our home page.

// start/routes.ts
router.on('/').render('pages/home').as('home')

By naming this route definition, we can reference it using "home" instead of its path ("/"). Why might we want to do this?

The first reason is type-safety. When we generate or refer to these routes within TypeScript, AdonisJS takes steps to ensure we're using routes that are actually defined at the type level.

If we check out the .adonisjs folder again, remember this is where AdonisJS places its auto-generated files, we'll find a routes.d.ts file within the server folder. AdonisJS generates this file listing our defined routes and their required parameters as well. If you'll notice, so far, the as() method is only being used at home, yet all of these routes have names associated with them as the key.

// .adonisjs/server/routes.d.ts
import '@adonisjs/core/types/http'

type ParamValue = string | number | bigint | boolean

export type ScannedRoutes = {
  ALL: {
    'home': { paramsTuple?: []; params?: {} }
    'challenges.index': { paramsTuple?: []; params?: {} }
    'challenges.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'challenges.create': { paramsTuple?: []; params?: {} }
    'challenges.store': { paramsTuple?: []; params?: {} }
    'challenges.edit': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'challenges.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'new_account.create': { paramsTuple?: []; params?: {} }
    'new_account.store': { paramsTuple?: []; params?: {} }
    'session.create': { paramsTuple?: []; params?: {} }
    'session.store': { paramsTuple?: []; params?: {} }
    'session.destroy': { paramsTuple?: []; params?: {} }
  }
  GET: {
    'home': { paramsTuple?: []; params?: {} }
    'challenges.index': { paramsTuple?: []; params?: {} }
    'challenges.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'challenges.create': { paramsTuple?: []; params?: {} }
    'challenges.edit': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'new_account.create': { paramsTuple?: []; params?: {} }
    'session.create': { paramsTuple?: []; params?: {} }
  }
  HEAD: {
    'home': { paramsTuple?: []; params?: {} }
    'challenges.index': { paramsTuple?: []; params?: {} }
    'challenges.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'challenges.create': { paramsTuple?: []; params?: {} }
    'challenges.edit': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
    'new_account.create': { paramsTuple?: []; params?: {} }
    'session.create': { paramsTuple?: []; params?: {} }
  }
  POST: {
    'challenges.store': { paramsTuple?: []; params?: {} }
    'new_account.store': { paramsTuple?: []; params?: {} }
    'session.store': { paramsTuple?: []; params?: {} }
    'session.destroy': { paramsTuple?: []; params?: {} }
  }
  PUT: {
    'challenges.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
  }
}
declare module '@adonisjs/core/types/http' {
  export interface RoutesList extends ScannedRoutes {}
}

This is because AdonisJS will now default to a name built from the controller's name and the method used for the route from that controller, giving us challenges.index as an auto-generated name for our /challenges route. When we refer to routes using their names, AdonisJS will use this file to ensure that the route exists and that we meet its requirements.

Let's start with our redirects within our ChallengesController as this will allow us to get TypeScript feedback. Instead of doing response.redirect('/challenges'), we can chain an additional toRoute() method off our redirection.

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  async store({ request, response }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)

    challenges.push({ id: challenges.length + 1, ...data })

++    return response.redirect().toRoute('challenges.index')
  }

  // ...
}

This accepts the route's name as the first argument and any route parameters as an object in the second. So if, for example, we wanted to redirect the user back to the challenge show page after updating, we could do:

// app/controllers/challenges_controller.ts
export default class ChallengesController {
  // ...

  async update({ params, request, response }: HttpContext) {
    const data = await request.validateUsing(challengeValidator)

    // find the challenge being updated by its id, and update its data
    const challengeIndex = challenges.findIndex((row) => row.id === params.id)
    challenges[challengeIndex] = { id: params.id, ...data }

++    return response.redirect().toRoute('challenges.show', { id: params.id })
  }

  // ...
}

Note, with this, if we get the identifier wrong or omit the params, we get a type error to match, keeping things type-safe.

The other reason we might want to use identifiers is that route patterns are prone to change over time. By using the route's name instead of the pattern, we're saving ourselves the pain of having to search down all of the route's usages because the name we're using will automatically pick up pattern changes.

Generating Route URLs

We can also get access to the URL builder that toRoute is used under the hood to build out a URL via the identifier as well. For example:

// app/controllers/challenges_controller.ts
import { urlFor } from '@adonisjs/core/services/url_builder'
export default class ChallengesController {
  // ...

  async show({ view, params }: HttpContext) {
    const challenge = challenges.find((row) => row.id === params.id)
++    const editUrl = urlFor('challenges.edit', { id: params.id })

++    return view.render('pages/challenges/show', { challenge, editUrl })
  }

  // ...
}

Finally, this is also available within our EdgeJS templates via a global helper method called route.

// resources/views/pages/challenges/create.edge
@layout()

  <div>
    <div class="hero">
      <h1>Challenges</h1>
  
      @include('partials/challenge/available_points')
  
++      <a href="{{ route('challenges.create') }}" class="button">Create a new challenge</a>
    </div>

    @challenge.grid() 
      @each(challenge in challenges)
        @!challenge.gridItem({ challenge }) 
      @endeach
    @end
  </div>

@end

We've got a few spots to update this.

// resources/views/components/challenge/grid_item.edge

++<a href="{{ route('challenges.show', { id: challenge.id }) }}">
  <h3>{{ challenge.text }}</h3>
  <p>Points: {{ challenge.points }}</p>
</a>

We gave ourselves an editUrl on our show page, so we can make use of that if we'd like.

// resources/views/pages/challenges/show.edge
@layout()

  <div class="hero">
    <h1>{{ challenge.text }}</h1>
    <p>Points: {{ challenge.points }}</p>

++    <a href="{{ editUrl }}" class="button">Edit Challenge</a>
  </div>

@end

Form Component

Finally, we have our forms. Like the fields, the starter kit also gave us a form component which will automatically include our csrfField() on non-GET requests! This component accepts the route identifier and route params as separate props, then builds those into our route URL for us.

// resources/views/pages/challenges/create.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Create Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      @form({ route: 'challenges.store', method: 'POST' })
        <div>
          @field.root({ name: 'text' })
            @!field.label({ text: 'Text' })
            @!input.control({ type: 'text' })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'points' })
            @!field.label({ text: 'Points' })
            @!input.control({ type: 'number' })
            @!field.error()
          @end
        </div>

        <div>
          <button type="submit" class="button"> Create Challenge </button>
        </div>
      @end
    </div>
  </div>

@end

Of note, the form component also automatically handles our HTTP method spoofing, so we can directly set the method here as "PUT" and it'll do the rest.

// resources/views/pages/challenges/edit.edge
@layout()

  <div class="form-container">
    <div>
      <h1> Edit Challenge </h1>
      <p> Enter your challenge details below </p>
    </div>

    <div>
      @form({ method: 'PUT', route: 'challenges.update', routeParams: { id: challenge.id } })
        <div>
          @field.root({ name: 'text' })
            @!field.label({ text: 'Text' })
            @!input.control({ type: 'text', value: challenge.text })
            @!field.error()
          @end
        </div>

        <div>
          @field.root({ name: 'points' })
            @!field.label({ text: 'Points' })
            @!input.control({ type: 'number', value: challenge.points })
            @!field.error()
          @end
        </div>

        <div>
          <button type="submit" class="button"> Update Challenge </button>
        </div>
      @end
    </div>
  </div>

@end

For example, if we want to identify a competition by its id, we can define the pattern as /competitions/:id. Route parameters are designated by a colon (:), and the term that follows is the parameter's name, the property with which we can access the dynamic value.

// start/routes.ts
router.get('/challenge/:id', async (ctx) => {
  const challengeId = ctx.params.id
  return challengeId
})

Our HttpContext provides a params object containing parsed route parameters. Since we've named our param id, that is the property name we can access the value with. Up til now, we've rendered an HTML page using EdgeJS. For now, let's just simply return this ID to see what we get!

When we request this with our browser, we get back a plaintext response. By default, AdonisJS will utilize content negotiation to determine the appropriate content type to respond with using the Accept header. If we instead specify this specifically as a JSON response, using the response on our HttpContext, we'll see our browser switches to a JSON viewer to match the new content-type of our response.

// start/routes.ts
router.get('/challenge/:id', async (ctx) => {
  const challengeId = ctx.params.id
++  return ctx.response.json({ id: challengeId })
})

Route Machers/Validators

If you noticed, our value is coming back as a string. Meaning, if we were to move our challenges array out where this route can utilize it as well, we would need to convert the type of the parameter in order to find a 1:1 strict-equality match.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

++const challenges = [
++  { id: 1, text: 'Learn AdonisJS', points: 10 },
++  { id: 2, text: 'Learn EdgeJS', points: 5 },
++  { id: 3, text: 'Build an AdonisJS app', points: 20 },
++]

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router.get('/challenges', async (ctx) => {
  return ctx.view.render('pages/challenges/index', { challenges })
})

router.get('/challenge/:id', async (ctx) => {
++  const challenge = challenges.find((row) => row.id === Number(ctx.params.id))
++  return ctx.response.json({ challenge })
})

Instead of doing this, we can utilize route parameter matches and validation to:

1. Ensure the ID is a valid number for this route pattern to actually be matched against

2. Cast the ID route parameter to a number within our params object.

// start/routes.ts
router.get('/challenge/:id', async (ctx) => {
  const challenge = challenges.find((row) => row.id === Number(ctx.params.id))
  return ctx.response.json({ challenge })
++}).where('id', /^[0-9]+$/)

Here, we're using regex to merely ensure the id route parameter is a number. If it isn't, the route won't be matched, and currently, that would result in us getting a 404 Not Found exception.

If we wanted to cast it to a number, we could add a cast to the validation.

// start/routes.ts
router
  .get('/challenge/:id', async (ctx) => {
++    const challenge = challenges.find((row) => row.id === ctx.params.id)
    return ctx.response.json({ challenge })
  })
++  .where('id', { 
++    match: /^[0-9]+$/,
++    cast: (value) => Number(value)
++  })

Now, we're both ensuring it's a number and casting it from a string value to a number value. So our ctx.params.id is actually a number now, meaning we can get rid of the cast there. This is a common scenario, and AdonisJS knows that, so there is a convenient matcher we can use to perform this exact flow in a simplified manner.

// start/routes.ts
router.get('/challenge/:id', async (ctx) => {
  const challenge = challenges.find((row) => row.id === ctx.params.id)
  return ctx.response.json({ challenge })
++}).where('id', router.matchers.number())

You'll notice there is also a matcher for slug and UUID, doing similar things there. If, like our IDs, you're always going to want a route parameter to be cast or validated, we can apply this globally across all our routes.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

++router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router.get('/challenges', async (ctx) => {
  return ctx.view.render('pages/challenges/index', { challenges })
})

router.get('/challenge/:id', async (ctx) => {
  const challenge = challenges.find((row) => row.id === ctx.params.id)
  return ctx.response.json({ challenge })
})

Now, anytime we use the name id for a route parameter, our number matcher will be used to validate and cast it.

Okay, finally, let's rig this up to a page!

node ace make:view pages/challenges/show

// resources/views/pages/challenges/show.edge
@layout()

  <div>
    <h1>{{ challenge.text }}</h1>
    <p>Points: {{ challenge.points }}</p>
  </div>

@end

Then, we need to render the page instead of returning JSON as well. We can also spread specific properties out of our HttpContext as well to simplify our code a little as well.

// start/routes.ts
router.get('/challenge/:id', async ({ view, params }) => {
  const challenge = challenges.find((row) => row.id === params.id)
  return view.render('pages/challenges/show', { challenge })
})

We can now also link to this page from our /challenges page using an anchor element.

// resources/views/pages/challenges/index.edge
@let(availablePoints = challenges.reduce((total, challenge) => total + challenge.points, 0))

@if (completedChallenges?.length)
  @let(completedPoints = completedChallenges.reduce((total, challenge) => total + challenge.points, 0))
  @assign(availablePoints = availablePoints - completedPoints)
@endif

@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    <div>
      Total Points Available: {{ availablePoints }}
    </div>

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    <ul>
      @each(challenge in challenges)
        <li>
++          <a href="/challenges/{{ challenge.id }}">
            <h3>{{ challenge.text }}</h3>
            <p>Points: {{ challenge.points }}</p>
          </a>
        </li>
      @endeach
    </ul>
  </div>

@end

Our interpolation here will inject the challenge ID we're currently looping over into the href path to form our completed URL. We'll expand on this later on with a more sustainable linking approach.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

router.get('/challenges', async (ctx) => {
  return ctx.view.render('pages/challenges/index', { challenges })
})

router.get('/challenge/:id', async ({ view, params }) => {
  const challenge = challenges.find((row) => row.id === params.id)
  return view.render('pages/challenges/show', { challenge })
})

// ...

This might be fine for small applications, but scales poorly for anything beyond a few routes. The remedy for this is controllers. Controllers are classes with dedicated methods to serve as our route handlers. This moves the logic of our routes from the route definitions into dedicated controller files, typically grouped by resource, like our challenge resource.

Creating Controllers

We can quickly create a new controller using the Ace CLI, but before we do, let's review the help options for this command.

node ace make:controller --help
# 
# Description:
#   Create a new HTTP controller class
# 
# Usage:
#   node ace make:controller [options] [--] <name> [<actions...>]
# 
# Arguments:
#   name            The name of the controller
#   [actions...]    Create controller with custom method names
# 
# Options:
#   -s, --singular  Generate controller in singular form
#   -r, --resource  Generate resourceful controller with methods to perform CRUD actions on a resource
#   -a, --api       Generate resourceful controller without the "edit" and the "create" methods

The naming convention for controllers is for them to be plural, and AdonisJS will help us out with that by automatically pluralizing the name we provide it for our controller. If we want to bypass that, we can add --singular, or -s for short.

If you'll recall from a few lessons ago, we discussed resourceful naming conventions with index, create, store, edit, update, and delete. To create a resourceful controller with methods stubbed to handle each of those actions, we can add --resource, or -r for short.

If you're working on an API, you won't need the create or edit, so you can create a resource with those omitted with --api or -a for short.

Finally, we could also manually specify methods we want to stub or provide nothing at all to get a simple class. Let's go ahead and create this as a resourceful controller.

node ace make:controller challenge -r
# DONE:    create app/controllers/challenges_controller.ts

Controllers can be found within our app/controllers folder. Again, note this automatically pluralized "challenge" to "challenges" for our controller name. Once we jump into this new file, we should see the following.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({}: HttpContext) {}

  /**
   * Display form to create a new record
   */
  async create({}: HttpContext) {}

  /**
   * Handle form submission for the create action
   */
  async store({ request }: HttpContext) {}

  /**
   * Show individual record
   */
  async show({ params }: HttpContext) {}

  /**
   * Edit individual record
   */
  async edit({ params }: HttpContext) {}

  /**
   * Handle form submission for the edit action
   */
  async update({ params, request }: HttpContext) {}

  /**
   * Delete record
   */
  async destroy({ params }: HttpContext) {}
}

First thing to note here is that each of the method's arguments is typed with HttpContext. Within our route definition's callback methods, the HttpContext can be automatically typed by the definition. In our controller context, however, that inference can't happen, so a type is needed. Second, AdonisJS has started each method with a request extracted out of the HttpContext for methods expecting data to be sent up, like creating and updating records. Params are extracted for those that typically use a route parameter to identify a single record, like our challenge's id.

So, for us, we want to move our challenges array to the top of this file, so we still have that data to work with.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

++const challenges = [
++  { id: 1, text: 'Learn AdonisJS', points: 10 },
++  { id: 2, text: 'Learn EdgeJS', points: 5 },
++  { id: 3, text: 'Build an AdonisJS app', points: 20 },
++]

export default class ChallengesController {
  // ...
}

Then, we can take the inner contents of our /challenges route definition and move it into our index method. We can also extract view out of the HttpContext for consistency.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  /**
   * Display a list of resource
   */
++  async index({ view }: HttpContext) {
++    return view.render('pages/challenges/index', { challenges })
  }
  
  // ...
}

Then, we can do the same for our /challenges/:id route definition. This route's job is to show a single record, so its resourceful method will be show.

// app/controllers/challenges_controller.ts
import type { HttpContext } from '@adonisjs/core/http'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

export default class ChallengesController {
  /**
   * Display a list of resource
   */
  async index({ view }: HttpContext) {
    return view.render('pages/challenges/index', { challenges })
  }

  // ...

  /**
   * Show individual record
   */
++  async show({ view, params }: HttpContext) {
++    const challenge = challenges.find((row) => row.id === params.id)
++    return view.render('pages/challenges/show', { challenge })
  }
  
  // ...
}

Using Controllers

We then need to update our route definitions to point to these controller methods instead of using the callback function. For this, we'll provide an array as the second argument to our route definition with our controller and the designated method to be used to handle the route. You'll also notice that AdonisJS provides a nice type inference to give us an autocomplete list of the controller's methods to pick from as well.

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'
++const ChallengesController = () => import('#controllers/challenges_controller')

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

++router.get('/challenges', [ChallengesController, 'index'])
++router.get('/challenge/:id', [ChallengesController, 'show'])

// ...

Here, AdonisJS prefers lazy-loaded controllers, hence the wrapped import. This helps ensure a speedy boot as we get more and more controllers to be imported.

Barrel Files & Subpath Imports

New in AdonisJS 7 is a new barrel file generation step. If we look at the top of our imports and the starter kit's pre-defined routes, we'll notice controllers is being imported from a #generated/controllers location.

This location is utilizing a NodeJS Subpath Import, which is an alias import location to simplify our import paths throughout our project. Let's start here, these are defined within our package.json file, and AdonisJS comes with several out-of-the-box.

// package.json
{
  "": "...",

  "imports": {
    "#controllers/*": "./app/controllers/*.js",
    "#exceptions/*": "./app/exceptions/*.js",
    "#models/*": "./app/models/*.js",
    "#mails/*": "./app/mails/*.js",
    "#services/*": "./app/services/*.js",
    "#listeners/*": "./app/listeners/*.js",
    "#generated/*": "./.adonisjs/server/*.js",
    "#events/*": "./app/events/*.js",
    "#middleware/*": "./app/middleware/*.js",
    "#validators/*": "./app/validators/*.js",
    "#providers/*": "./providers/*.js",
    "#policies/*": "./app/policies/*.js",
    "#abilities/*": "./app/abilities/*.js",
    "#database/*": "./database/*.js",
    "#tests/*": "./tests/*.js",
    "#start/*": "./start/*.js",
    "#config/*": "./config/*.js"
  },

  "": "...",
}

This is saying, anytime we're importing from #generated to look within ./.adonisjs/server/ from our project root. So, our #generated/controllers import location is actually ./.adonisjs/server/controllers.ts within our project.

The .adonisjs folder is a new folder to AdonisJS 7 for these automatically generated files to improve type-safety throughout AdonisJS applications. Generated types and files to be used on the server-side will be within .adonisjs/server, while client-side safe types will be within .adonisjs/client. Since these are generated, they shouldn't be manually updated, as any updates will be overwritten.

So, if we open our generated controllers file, we'll see something like:

// .adonisjs/server/controllers.ts
export const controllers = {
  Challenges: () => import('#controllers/challenges_controller'),
  NewAccount: () => import('#controllers/new_account_controller'),
  Session: () => import('#controllers/session_controller'),
}

These generated files are created during and while our dev server is booted. So if you stop your server and create a controller, this won't update until we boot the dev server back up.

As we can see, this is an object of keys named after our controllers pointing to their import locations, again using lazy-loading as well to keep things loading efficiently. This is called a barrel file, and its purpose is to cut back on import clutter. Rather than importing every controller our application uses, we can instead import this one controllers variable and reference the controller's import location from here.

So, to use this, we can swap our import and class for controllers.Challenges. This, too, will give us a type inference autocomplete list of methods from the controller, same as we had before!

// start/routes.ts
import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

const challenges = [
  { id: 1, text: 'Learn AdonisJS', points: 10 },
  { id: 2, text: 'Learn EdgeJS', points: 5 },
  { id: 3, text: 'Build an AdonisJS app', points: 20 },
]

router.where('id', router.matchers.number())

router.on('/').render('pages/home').as('home')

router.on('/terms').render('pages/terms')

++router.get('/challenges', [controllers.Challenges, 'index'])
++router.get('/challenge/:id', [controllers.Challenges, 'show'])

// ...

When we request our /challenges route now, AdonisJS will instantiate an instance of our ChallengesController and execute the index method, passing it the HttpContext. Each request gets its own isolated controller instance.

Resources

Since we're using a resourceful controller, AdonisJS provides a utility route definition to automatically define a route for each of the resourceful actions. So, we could define all six of these resourceful routes for our challenges with:

// start/routes.ts
router.resource('challenges', controllers.Challenges)

This takes the name we've provided to define the base of all these routes as /challenges and it will then add the id route parameter where appropriate. The route handlers will also map automatically to the correct controller method for the route as well.

If we created an API resource, we could add apiOnly() to this to omit the create and edit routes. We can also use only() to specify specific resource routes to define.

// start/routes.ts
router.resource('challenges', controllers.Challenges).only(['index', 'show'])

We have a little more to learn yet, however, so I'm going to keep these as separate routes for now.

// start/routes.ts
router.get('/challenges', [controllers.Challenges, 'index'])
router.get('/challenge/:id', [controllers.Challenges, 'show'])

I want to just take a brief moment to talk about what will follow. Once I've got my Let's Learn AdonisJS 7 series fully completed and released, I'll be taking at least a 90 day seasonal break. And, just to be very clear, this is just a break, I'm not quitting Adocasts! I've actually been kind of hesitant to post this, but here we go.

Why the Break? (Part One: It's Me)

Building Adocasts alongside a full-time career has been a rewarding journey, and I'm thankful for each and every one of you who've supported me and watched my lessons along the way. I've spent a lot of time these past couple of months reflecting on something new I've realized about myself. I've also been reflecting on the time commitment Adocasts takes, how that time impacts my life, and the trajectory of learning in the face of AI.

Over the past couple of months I've become aware that I strongly fit the profile of someone with Aspergers Syndrome, an Autism Spectrum Disorder (ASD). I'm currently debating whether I want to go through the process of an official diagnosis, but from what I've read it's a time consuming and expensive process without a whole lot of benefits (beyond the certainty of knowing). Regardless of a diagnosis or not, I'm hoping some of the frameworks found to help those with a diagnosis can help me as well. It also helps answer some long standing questions I've always had about myself too.

Among other things, I've always:

• Felt different from everyone else and always felt like I was acting my way through social situations. Following procedures and expectations while others seem to naturally flow through dialog.

• Been a super quiet person who prefers being alone.

• Get extremely drained from any social gathering - any!

• Get stressed if rules or social norms are being deviated

• Felt like there is a layer of encryption between my mind and body

• Had a tendency to give short one or two word answers to questions in conversation.

• Rehearsed for the smallest of things... My low-stakes weekly standup at work, yep! Gotta script that out and say it til it's smooth.

• Lived by both large and small routines and when they're broken it drastically upsets my day and mood

• Swayed back and forth while standing, shaked my knees when sitting, and cracked my fingers when distressed, etc

I could go on, but I already feel like I'm sharing too much. Most applicable here is that I realized coding is my special interest. Unlike most things in life, it came naturally to me and sunk me in immediately. I've always hated the fact that it's my job because it's something I have fun doing. It being a job sucks that fun away leaving just the time after work when I'm already tired. I have found that working with things I don't get to use at work brings that joy and experimentation back though.

Adocasts started as a branch of that joy I found in my post-work time. However, over the past couple of years I've inadvertently slowly turned this fun hobby portion of my special interest into a second job. That shift, started sneakily depleting me because now my special interest is all work and no play. I just haven't had the energy to work on or explore new things outside of work and the requirements needed to push new content for Adocasts. I have had quiet periods where I haven't posted lessons, but trust me, preparing them takes a lot of time, especially on a tired mind.

So, I've decided forcing myself to take a break is the best path forward. I need to do a hard reset on my routine as it relates to Adocasts and figure out what works for me and what I would like to do to "spark joy" back into my interest so it isn't all work.

Why the Break? (Part Two: It's AI)

There's another edge to this sword, called AI. We all know AI is making waves through our industry and siphoning eyes from sites to boot. Adocasts traffic is down*, revenue is down, and more and more people mention they're only reaching out for help after AI let them down. No judgement here, It makes sense! AI is quick, mostly free, and easily accessible plus you don't need to dig through site after site to find what you're after.

I, personally, am not at a point where I trust AI in unsupervised situations. It's just too unpredictable for me: often misunderstanding scope, referencing outdated information, and obfuscating it's sources. It's great for certain tasks, but I don't think learning is one of them at this time. If anything, it can sew more confusion than help in the context of learning. Obviously though, my take there is biased because it directly impacts Adocasts.

Regardless, even without AI, long-form ways of learning like I provide are on a downward trajectory. So, I want to take a portion of this time away to think about forward looking possibilities here. I don't know if there's an answer to be had, but I think stepping away for a brief bit will help bring clarity with envisioning a pathway forward.

If you have any thoughts, ideas, or know of anyone doing different things in this regard, I would absolutely love to hear them below in the comments!

What This Means

First, I again want to reiterate I'll be completing the Let's Learn AdonisJS 7 series before I take this break. Once that is done, I'll be going on at least a 90 day break. During this break I won't be releasing or planning any new content. I'll also be on light duty with social media and support, so responses may be slower than usual. I'll be using this time to reset myself and think about future possibilities to bring into Adocasts.

Effective today, I will be removing the "Forever" plan as an Adocasts Plus purchase option. If you are a current Forever member, fear not, nothing is changing for you! I'm simply closing this tier to new members until after my break to try and remove the mental load of having a "forever" commitment. I'm still committed, merely just doing some mental jiu-jitsu for myself there.

If you're an annual subscriber, I get that this is a deviation from my traditional release pattern and want to be as fair as possible. If this upcoming change in release frequency doesn't work for you, please reach out to me (tom@adocasts.com) and I'd be happy to assist with a pro-rated refund for your remaining time.

Again this isn't an end, just a break to reboot my system, find joy again in Adocasts, and find a pathway forward with the state of AI in mind. Thank you so much for being a part of this community and for your understanding as I take this step towards a healthier life balance. If you have any thoughts for Adocasts you'd like for me to mull over during my break, please do leave them below!

*Traffic is down - Of late, China alone accounts for 2x the traffic of everywhere else combined, I presume it's bots and have been trying to target it without flagging all of China. So, this is stated with the context of China omitted from traffic.

The Hypermedia Starter Kit gave us a few predefined routes.

// start/routes.ts
/*
|--------------------------------------------------------------------------
| Routes file
|--------------------------------------------------------------------------
|
| The routes file is used for defining the HTTP routes.
|
*/

import { controllers } from '#generated/controllers'
import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

router.on('/').render('pages/home').as('home')

router
  .group(() => {
    router.get('signup', [controllers.NewAccount, 'create'])
    router.post('signup', [controllers.NewAccount, 'store'])

    router.get('login', [controllers.Session, 'create'])
    router.post('login', [controllers.Session, 'store'])
  })
  .use(middleware.guest())

router
  .group(() => {
    router.post('logout', [controllers.Session, 'destroy'])
  })
  .use(middleware.auth())

First, it's importing the router container service. This is a singleton of AdonisJS's router, meaning the same single instance of this service is used every time it's imported for the duration of our server's life.

Several AdonisJS batteries export service containers for convenience, and can be noted by the /services/ import path.

With this router, we can define route definitions. Route definitions are paths we define for our application to handle. For example, when we booted our application in lesson 1.2, we saw a landing page. This is defined by the router.on('/') definition. The on method is a shorthand syntax that will define a GET route definition for the pattern provided with a few simple handling options, like rendering a page as it's doing here.

// start/routes.ts
  router
    .on('/')  // defines GET: / route definition for the pattern '/'
    .render('pages/home') // handles that route by rendering the home page
    .as('home') // names the route (more on this later)

In addition to the on shorthand method, each HTTP Verb has its own method that allows us fine-grain control over how to handle the route. Each HTTP Verb has a purpose.

• GET is for rendering pages and fetching information

• POST is for creating records and sending general payloads

• PUT is for updating a record (multiple properties)

• PATCH is for a targeted record update (singular properties)

• DELETE is for deleting records

Defining a Route

Let's start by creating a page of our own to show our application's terms of use, a page almost every application has.

router.on('/terms').render('pages/terms')

With this, we're saying that when we request the /terms pattern, we should render the page within resources/views/pages/terms.edge. When rendering, AdonisJS will automatically look within resources/views so we only need to specify the path from there. Now, we haven't created this page yet, so when we request this route, we'll be met with an error screen.

This error screen is Youch, an informative and developer-friendly error screen to tell us exactly what error we got and a stack trace to help track it down. This screen will only be displayed when our application is in development mode.

Error: Cannot resolve "/../lets-learn-adonisjs-7/resources/views/pages/terms.edge". Make sure the file exists

In this case, it's telling us it cannot resolve the page we've told it to render. Let's fix this by creating this page!

Creating Views

AdonisJS has its own templating engine called EdgeJS, which uses .edge as its file extension and the AdonisJS Extension Pack we installed in Module 1 adds support for EdgeJS to Visual Studio Code.

touch resources/views/pages/terms.edge

Then we can use emmet to quickly stub HTML5 markup with html:5 to get:

// resources/views/pages/terms.edge
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  
</body>
</html>

On our body, let's just add some simple text!

// resources/views/pages/terms.edge
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
++  <h1>Terms of Service</h1>
++  <p>This is the terms of service page.</p>
</body>
</html>

Now, if we refresh our browser, instead of being met by Youch with an error screen, we see our page!

Let's add another view, this time, using the Ace CLI!

node ace make:view pages/challenges/index
# DONE:    create resources/views/pages/challenges/index.edge

Our naming here of challenges/index follows resourceful naming conventions, where "challenge" is our resource. Resourceful naming has conventions for each HTTP operation needed to list, show, create, update, and delete a resource.

• GET /challenges uses the name index and renders a list of items for the resource

• GET /challenges/1 uses the name show and renders a single item, "1" here serves as an identifier.

• GET /challenges/create uses the name create and renders a form to create an item

• POST /challenges uses the name store and handles the form to create an item

• GET /challenges/1/edit uses the name edit and renders a form to edit an item

• PUT /challenges/1 uses the name update and handles the form to update an item

• DELETE /challenges/1 uses the name destroy and handles the deletion of an item

We'll see this naming convention used in both our route definitions and view names. Keeping to the convention helps keep things predictable and easily understandable.

Okay, let's add some simple HTML5 markup again, using html:5, with some basic text noting which page we're on.

// resources/views/pages/challenges/index.edge
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  <h1>Challenges</h1>
</body>
</html>

Rendering Views

Finally, let's define a route for this view so we can actually request and render it. This time, we'll use the get method. Unlike the on shorthand, this accepts a second argument allowing us fine-grained control over how the route should be handled via a route handler.

// start/routes.ts
router.get('/challenges', async (ctx) => {
  
})

The route handler is provided an HttpContext, contextual information about the request. It's with this that we can specify what page to render, gain access to request and response properties, and a lot more. As we continue through this series, we'll get more acquainted with the HttpContext, for now though, let's use it to render our page.

// start/routes.ts
router.get('/challenges', async (ctx) => {
++  return ctx.view.render('pages/challenges/index')
})

Our render method is chained off the view property within our HttpContext. This method is the same render method we used with our shorthand; however, this time you'll notice we get some convenient autocomplete options pulling from pre-existing pages within our application.

Okay, great with that saved, we should now be able to head to /challenges in our browser to see this page rendered out!

Before we move on, in case you're concerned that we have to manually refresh our browser to see our changes, don't worry! This is simply because our browser isn't hooked into our Vite dev server. We can fix this by applying our starter kit's layout component to the page. This layout comes pre-packaged with the HTML:5 boilerplate we already have on our page in addition to an @vite tag pointing to our CSS and JS file. It's this @vite tag that wires our browser up to our dev server to get our browser to automatically pick up changes we make in-code. There's a lot going on here; we'll slowly get comfortable with all of this. For now, we can swap our HTML5 boilerplate with our layout.

// resources/views/pages/challenges/index.edge
@layout()

  <h1>Challenges</h1>

@end

Anything in between the layout start and end tag is ultimately rendered out via the layout's main slot, again... more on that later!

// resources/views/components/layout.edge
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>
      AdonisJS - A fully featured web framework for Node.js
    </title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @stack('dumper')
  </head>
  <body>
    @include('partials/header')
    <main>
      @include('partials/flash_alerts')
      {{{ await $slots.main() }}}
    </main>
  </body>
</html>

So, if we add a paragraph to our challenges page...

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>
  </div>

@end

We'll see this automatically applied in our browser without the need to refresh manually!

We've already learned a little about interpolation and tags with EdgeJS, but we're going to drive it home here. For starters, we can do more than merely access state with interpolation; we can perform JavaScript expressions as well.

For example, if we wanted to show the total number of points available from our challenges, we could evaluate that aggregation within an interpolation!

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

++    <div>
++      Total Points Available: 
++      {{ challenges.reduce((total, challenge) => total + challenge.points, 0) }}
++    </div>
  </div>

@end

Note these interpolations can span multiple lines as well if you need to do something like a bracketed callback or if you're performing a longer ternary.

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    <div>
      Total Points Available: 
++      {{ 
++        challenges.reduce((total, challenge) => {
++          return total + challenge.points
++        }, 0) 
++      }}
    </div>
  </div>

@end

Conditionals & Loops

EdgeJS supports conditionals and loops as well via tags, so if we wanted to loop over our challenges, we could use @each to do just that!

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    <div>
      Total Points Available: 
      {{ 
        challenges.reduce((total, challenge) => {
          return total + challenge.points
        }, 0) 
      }}
    </div>

++    <ul>
++      @each(challenge in challenges)
++        <li>
++          <h3>{{ challenge.text }}</h3>
++          <p>Points: {{ challenge.points }}</p>
++        </li>
++      @endeach
++    </ul>
  </div>

@end

Here @each starts the loop and @endeach ends the loop. In between, we have access to the individual challenge currently being looped over. Now, as mentioned previously, tags must be on a line of their own. So, something like the below is invalid!

<ul> @each(challenge in challenges) {{ challenge.text }} @endeach </ul>

If we wanted to show a message in the event that we don't have any challenges, we can use a conditional!

// resources/views/pages/challenges/index.edge
@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    <div>
      Total Points Available: 
      {{ 
        challenges.reduce((total, challenge) => {
          return total + challenge.points
        }, 0) 
      }}
    </div>

++    @if (!challenges.length)
++      <p>No challenges available.</p>
++    @else
++      <p>Below are our available challenges:</p>
++    @endif

    <ul>
      @each(challenge in challenges)
        <li>
          <h3>{{ challenge.text }}</h3>
          <p>Points: {{ challenge.points }}</p>
        </li>
      @endeach
    </ul>
  </div>

@end

We can also utilize @elseif() if needed here as well, and we could use @unless instead of an @if as an alternative.

@unless (challenges.length)
  <p>No challenges available!</p>
@endunless

These native tags all come with supporting named end tags, for example @endif goes with @if. However, if you prefer, @end can be used as a consistent means to end any tag. I tend to prefer the named end tags as it signals what exactly it is we're ending, but to each their own.

Variables

Beyond state, we can also declare variables within our templates as well. We can use the @let tag to declare a new block-level variable and @assign to update a variable's value. This can be used in conjunction with conditionals to do something like the below!

// resources/views/pages/challenges/index.edge
++@let(availablePoints = challenges.reduce((total, challenge) => total + challenge.points, 0))

++@if (completedChallenges?.length)
++  @let(completedPoints = completedChallenges.reduce((total, challenge) => total + challenge.points, 0))
++  @assign(availablePoints = availablePoints - completedPoints)
++@endif

@layout()

  <div>
    <h1>Challenges</h1>
    <p>Welcome to the challenges page.</p>

    <div>
++      Total Points Available: {{ availablePoints }}
    </div>

    @if (!challenges.length)
      <p>No challenges available.</p>
    @else
      <p>Below are our available challenges:</p>
    @endif

    <ul>
      @each(challenge in challenges)
        <li>
          <h3>{{ challenge.text }}</h3>
          <p>Points: {{ challenge.points }}</p>
        </li>
      @endeach
    </ul>
  </div>

@end

Rendering Raw HTML

Now, as a means of security, the double curly-braced interpolation will escape HTML. So, if you find yourself needing to actually render out HTML, you'll want to use three curly braces instead of two! Three won't escape HTML while two will. As we saw in our layout component, the slot is using three. That's because the slot will actually return HTML to be rendered. So, if we were to switch that to just two, we can see exactly how that impacts our page.

// resources/views/components/layout.edge
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>
      AdonisJS - A fully featured web framework for Node.js
    </title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @stack('dumper')
  </head>
  <body>
    @include('partials/header')
    <main>
      @include('partials/flash_alerts')
++      {{ await $slots.main() }}
    </main>
  </body>
</html>

With that, now we're just seeing the HTML that should be rendered as HTML instead being rendered as text content. So, let's undo that to get our HTML back!

Escaping Interpolation

If we need to actually render double or triple curly braces on our page, we can use an @ to escape the interpolation to instead render the actual curly braces.

// resources/views/components/layout.edge
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>
      AdonisJS - A fully featured web framework for Node.js
    </title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @stack('dumper')
  </head>
  <body>
    @include('partials/header')
    <main>
      @include('partials/flash_alerts')
++      @{{{ await $slots.main() }}}
    </main>
  </body>
</html>

With that, we literally see "{{{ await $slots.main() }}}" printed out on our page, and EdgeJS bypasses the expression altogether. Again, let's undo that to get our slot back to rendering.

Comments

Finally, EdgeJS supports comments as well; the syntax is double curly braces with double hyphens.

// resources/views/components/layout.edge
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>
      AdonisJS - A fully featured web framework for Node.js
    </title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @stack('dumper')
  </head>
  <body>
    @include('partials/header')
    <main>
      @include('partials/flash_alerts')

      {{-- renders default slot content --}}
      {{{ await $slots.main() }}}
    </main>
  </body>
</html>