Getting Started

Installation

Install and configure the package using the following command :

node ace add @foadonis/magnify

Installs the @foadonis/magnify package using the detected package manager.

Registers the following service provider inside the adonisrc.ts file.

{
  providers: [
    // ...other providers
    () => import('@foadonis/magnify/providers/magnify')
  ]
}

Registers the following commands inside the adonisrc.ts file.

{
  providers: [
    // ...other providers
    () => import('@foadonis/magnify/commands')
  ]
}

Creates the config/magnify.ts file.
Defines the environment variables and their validation for the selected engine.
Install required dependencies.

Configure your Model

Magnify tries to be as easy as possible to configure. To accomplish that, it brings a Searchable mixin to make any Lucid model Searchable.

A Searchable model will be automatically synchronized with your Search engine.

app/models/post.ts

import { compose } from '@adonisjs/core/helpers'
import { BaseModel, column } from '@adonisjs/lucid/orm'
import { Searchable } from '@foadonis/magnify'

export default class Post extends compose(BaseModel, Searchable) {
  @column({ isPrimary: true })
  declare id: string

  @column()
  declare title: string
}

Configure your Search Engine

Depending on the engine you selected during the configuration of @foadonis/magnify you must configure the credentials and the indexes.

Algolia

Algolia automatically configure your indexes for you, you do not need any extra configuration.

Meilisearch

Meilisearch requires each index to be configured. To accomplish that, head over to your config/magnify.ts file.

For more informations about the available settings, head over the Official Meilisearch documentation.

config/magnify.ts

import env from '#start/env'
import { defineConfig, engines } from '@foadonis/magnify'

const magnifyConfig = defineConfig({
  default: 'meilisearch',
  engines: {
    meilisearch: engines.meilisearch({
      host: env.get('MEILISEARCH_HOST'),
      apiKey: env.get('MEILISEARCH_API_KEY'),
      indexSettings: {
        posts: {
          filterableAttributes: ['isPublished'],
          sortableAttributes: ['createdAt'],
        }
      },
    }),
  },
})

export default magnifyConfig

After configuring the indexes, run the command node ace magnify:sync-index-settings to synchronize the new configuration with Meilisearch.

In future versions of Magnify, the indexes configuration will be automatically infered from your model.

Typesense

Typesense requires each collection (index) to be configured. To accomplish that, head over to your config/magnify.ts file.

For more informations about the available settings, head over the Official Typesense documentation.

config/magnify.ts

import env from '#start/env'
import { defineConfig, engines } from '@foadonis/magnify'

const magnifyConfig = defineConfig({
  default: 'typesense',
  engines: {
    typesense: engines.typesense({
      apiKey: env.get('TYPESENSE_API_KEY'),
      nodes: [
        {
          url: env.get('TYPESENSE_NODE_URL'),
        },
      ],
      collectionSettings: {
        posts: {
          queryBy: ['title'],
          fields: [
            {
              name: 'title',
              type: 'string',
            },
            {
              name: 'isPublished',
              type: 'bool',
              optional: true,
            },
            {
              name: 'updatedAt',
              type: 'string',
            },
            {
              name: 'createdAt',
              type: 'string',
            },
          ],
        }
      },
    }),
  },
})

export default magnifyConfig

In future versions of Magnify, the indexes configuration will be automatically inferred from your model.

Import the Data

Magnify only synchronize your models when they get created, updated or removed. Meaning that any existing data created before the installation of Magnify will not appear directly in your search engine. This is the purpose of the magnify:import command.

node ace magnify:import '#models/user'

node ace magnify:import user

node ace magnify:import ./app/models/user.js

Start Searching

Once everything is configured, you can start searching over your Model:

const posts = await Post.search('Magnify').take(20).get()

You can find more informations in the Advanced Page.