Payload Algolia Search Plugin

A powerful Payload CMS plugin that provides seamless integration with Algolia search, including automatic indexing and manual reindexing capabilities.

Core Features

Installation

pnpm add @humaan/payload-algolia-search

Basic Usage

In the plugins array of your Payload Config, call the plugin with options:

import { algoliaSearchPlugin } from '@humaan/payload-algolia-search'

export const config = buildConfig({
  plugins: [
    algoliaSearchPlugin({
      collections: ['pages', 'posts'],
      credentials: {
        appId: process.env.ALGOLIA_APP_ID!,
        adminApiKey: process.env.ALGOLIA_ADMIN_API_KEY!,
        indexName: process.env.ALGOLIA_INDEX_NAME!,
      },
    }),
  ],
})

Environment Variables

Create a .env file with your Algolia credentials:

ALGOLIA_APP_ID="your_algolia_app_id"
ALGOLIA_ADMIN_API_KEY="your_algolia_admin_api_key"
ALGOLIA_INDEX_NAME="your_index_name"

The adminApiKey credential must be an Algolia Admin API key, or an API key with the settings, editSettings, addObject, deleteObject, and browse ACLs. Never expose this key to the client.

When Payload initializes, the plugin configures collection as a filter-only facet on the configured Algolia index. This setting is required for collection reindexing. Existing facets and other index settings are preserved. The configured index must exist before Payload initializes.

Options

collections

The collections property is an array of collection slugs to enable syncing to search. Enabled collections receive a beforeChange and afterDelete hook that creates, updates, and deletes its respective search record as it changes over time.

beforeSync

Before creating or updating a search record, the beforeSync function runs. This is an afterChange hook that allows you to modify the data or provide fallbacks before its search record is created or updated.

// payload.config.ts
{
  // ...
  searchPlugin({
    beforeSync: ({ originalDoc, searchDoc }) => ({
      ...searchDoc,
      // - Modify your docs in any way here, this can be async
      // - You also need to add the `excerpt` field in the `searchOverrides` config
      excerpt: originalDoc?.excerpt || 'This is a fallback excerpt',
    }),
  }),
}

syncDrafts

When syncDrafts is true, draft documents will be synced to search. This is false by default. You must have Payload Drafts enabled for this to apply.

reindexBatchSize

A number that, when specified, will be used as the value to determine how many search documents to fetch for reindexing at a time in each batch. If not set, this will default to 50.

Collection reindexing

Collection reindexing allows you to recreate search documents from your search-enabled collections on demand. This is useful if you have existing documents that don't already have search indexes, commonly when adding plugin-algolia-search to an existing project. To get started, navigate to the Algolia Search global and click the pill in the top right actions slot of the list view labelled Reindex. This will open a popup with options to select one of your search-enabled collections, or all, for reindexing.

Releasing

Releases are driven by the shared workflows in humaan/actions.

1. In the Actions tab, run Start release and pick the bump type (patch, minor, major, prerelease or a custom version). It bumps package.json, regenerates CHANGELOG.md from the Conventional Commit PR titles, opens a chore(release): vX.Y.Z pull request as humaan-bot and enables auto-merge.
2. Once the required checks pass, the pull request squash-merges on its own.
3. Publish release (automatic) runs after CI succeeds on main. When the merged commit is a chore(release): commit it publishes to npm via trusted publishing, tags vX.Y.Z and creates the GitHub release. Any other commit on main is ignored.

Pull request titles must follow Conventional Commits because the changelog and release notes are generated from them. To preview a bump locally without opening a PR, run pnpm release:bump <patch|minor|major|prerelease|x.y.z> and discard the changes afterwards.