Get started with Laravel Scout and Vue InstantSearch

This tutorial targets Laravel 10 or later, with Vite and Vue 3.

While Scout seamlessly wraps the Algolia engine, the Vue.js bundle simplifies the use of Algolia’s InstantSearch library. For this tutorial, you need a fresh Laravel application. You’ll index a Contact model, which holds a name, an email, a company, and a state. The tutorial consists of 4 steps:

Create the model class and seed the database
Install Scout Extended, then index your data
Install Vue InstantSearch
Build your search experience

Create the model

Create an empty model and a migration file with the corresponding artisan command.

Command line

php artisan make:model -m Contact

This creates a model class in app/Models/Contact.php and a migration in database/migrations/DATE_create_contacts_table.php. Edit this migration file so it looks like this:

PHP

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('contacts', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email');
            $table->string('company')->nullable();
            $table->string('state')->nullable();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('contacts');
    }
};

Now that your Laravel app knows what a contact is, you can migrate the database to reflect these changes.

Command line

php artisan migrate

Import your fake data

Now you need to import data from Algolia’s contacts dataset and place it at the root of your resources folder. Create a seeder class so that you can select what data to import.

Command line

php artisan make:seeder ContactSeeder

Laravel generated a new database/seeders/ContactSeeder.php file. Open it up and edit it to add the following class.

PHP

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class ContactSeeder extends Seeder
{
    /**
     * Run the database seeds.
     */
    public function run(): void
    {
        $contacts = [];

        $raw = json_decode(
            file_get_contents(resource_path('contacts.json')),
            true
        );

        foreach ($raw as $contact) {
            $contacts[] = [
                'name' => $contact['firstname'].' '.$contact['lastname'],
                'email' => $contact['email'],
                'company' => $contact['company'],
                'state' => $contact['state'],
            ];
        }

        DB::table('contacts')->insert($contacts);
    }
}

This class opens the JSON dataset and pushes what you need into the database. You can now seed your database:

Command line

php artisan db:seed --class=ContactSeeder

Install Scout Extended

Install Scout Extended with Composer. It automatically pulls in Laravel Scout and Algolia’s PHP API client as dependencies, so this is the only package you need to require.

Command line

composer require algolia/scout-extended

Thanks to Laravel’s package auto-discovery, the service provider is registered for you. Create a scout.php file in your config folder with the following command:

Command line

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Configure Algolia’s credentials

Go to the Algolia dashboard, to the API keys section. You can find three important credentials there:

Your application ID
Your search-only API key
Your admin API key

You need to put these in your .env file. Don’t put these credentials directly in your config/scout.php file, they shouldn’t be part of your version history. Scout defaults to the collection driver, so you also need to set SCOUT_DRIVER to algolia.

.env

SCOUT_DRIVER=algolia

ALGOLIA_APP_ID=# Your Algolia application ID
ALGOLIA_SECRET=# Your Algolia write API key

VITE_ALGOLIA_APP_ID="${ALGOLIA_APP_ID}"
VITE_ALGOLIA_SEARCH_KEY=# Your search-only API key

The VITE_ variables are exposed to your frontend JavaScript code later in this tutorial. Only use the search-only API key in the frontend, never the admin key.

Index your data

Laravel Scout provides a convenient way to index your data: all you need to do is add a trait to your model. This trait adds functionalities to the default Model class, including keeping your data in sync with Algolia. Open up your app/Models/Contact.php file and add the Laravel\Scout\Searchable trait.

PHP

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Contact extends Model
{
    use Searchable;
}

Before you can keep your data in sync, you need to perform a batch import the first time. Scout has added a command for this.

Command line

php artisan scout:import "App\Models\Contact"

Scout Extended’s scout:import command flushes the index before importing, so any existing records in the index are removed first.

Take a look at your dashboard and you should be able to see your data.

Setup Vue.js

You should use frontend search, which gives your users instant results, and also frees up your server from processing every search request. You can use Vue InstantSearch to create a frontend search without writing a lot of custom JavaScript code to handle complex search behaviors.

Install Vue InstantSearch

Laravel uses Vite to bundle frontend assets, but doesn’t ship with Vue by default. Install Vue 3, the Vite plugin for Vue, and the search dependencies with npm.

Command line

npm install vue @vitejs/plugin-vue vue-instantsearch algoliasearch instantsearch.css

vite.config.js

import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    laravel({
      input: ["resources/css/app.css", "resources/js/app.js"],
      refresh: true,
    }),
    vue(),
  ],
});

Then, open up your resources/js/app.js file, create the Vue app, and register Vue InstantSearch as a plugin.

JavaScript

import { createApp } from "vue";
import InstantSearch from "vue-instantsearch/vue3/es";

const app = createApp({});

app.use(InstantSearch);

app.mount("#app");

Build your search experience

Compile JavaScript code

To compile your JavaScript code and rebuild it every time you change one of your files, start the Vite development server:

Command line

npm run dev

Defining where Vue renders

The app.js file from the previous step mounts Vue inside an #app tag.

HTML

<div id="app"></div>

Create a new file in your resources/js/components directory called MySearch.vue and register it in app.js for the search interface:

JavaScript

import MySearch from "./components/MySearch.vue";

app.component("my-search", MySearch);

Then update the blade view, adding the my-search component and the @vite directive:

Blade

<div id="app">
    <my-search />
</div>
@vite(['resources/css/app.css', 'resources/js/app.js'])

You can use Vue Devtools to debug your Vue components.

To use InstantSearch’s default theming, import it in resources/css/app.css.

CSS

@import "instantsearch.css/themes/algolia-min.css";

InstantSearch components

Every InstantSearch component needs to be inside an <ais-instant-search> tag. This lets the library know how to contact Algolia servers. You can set this up in MySearch.vue, using the VITE_ environment variables you added to your .env file earlier.

Vue

<template>
  <ais-instant-search :search-client="searchClient" index-name="contacts">
    <!-- Other search components go here -->
  </ais-instant-search>
</template>

<script>
import { liteClient as algoliasearch } from 'algoliasearch/lite'

export default {
  data() {
    return {
      searchClient: algoliasearch(
        import.meta.env.VITE_ALGOLIA_APP_ID,
        import.meta.env.VITE_ALGOLIA_SEARCH_KEY
      ),
    }
  },
}
</script>

To generate a search key that’s restricted to a single model instead, use the Algolia::searchKey() method. For more information, see Client-side search.

The library provides ready-to-use components to add a search box and display the results.

Vue

<ais-instant-search :search-client="searchClient" index-name="contacts">
  <ais-search-box placeholder="Search contacts..."></ais-search-box>
  <ais-hits></ais-hits>
</ais-instant-search>

By default, the component just shows the ID of the results. You can pass a template to change how your results display.

Vue

<ais-hits>
  <template v-slot:item="{ item }">
    <h1>
      <ais-highlight
        :hit="item"
        attribute="name"
      />
    </h1>
    <h4>
      <ais-highlight
        :hit="item"
        attribute="company"
      /> -
      <ais-highlight
        :hit="item"
        attribute="state"
      />
    </h4>

    <ul>
      <li>{{ item.email }}</li>
    </ul>

  </template>
</ais-hits>

Get started

Indexing

Searching

Production

Advanced use cases

Get started with Laravel Scout and Vue InstantSearch

Create the model

Import your fake data

Install Scout Extended

Configure Algolia’s credentials

Index your data

Setup Vue.js

Install Vue InstantSearch

Build your search experience

Compile JavaScript code

Defining where Vue renders

InstantSearch components

See also

​Create the model

​Import your fake data

​Install Scout Extended

​Configure Algolia’s credentials

​Index your data

​Setup Vue.js

​Install Vue InstantSearch

​Build your search experience

​Compile JavaScript code

​Defining where Vue renders

​InstantSearch components

​See also

Create the model

Import your fake data

Install Scout Extended

Configure Algolia’s credentials

Index your data

Setup Vue.js

Install Vue InstantSearch

Build your search experience

Compile JavaScript code

Defining where Vue renders

InstantSearch components

See also