OpenParable
Skip to content
← Back to skills

Stacks Search Engine

Development
stacks-search-engine

Stacks Search Engine is an Agent Skill for development published in the stacksjs/stacks repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when implementing search in Stacks — full-text search with Meilisearch or Algolia backends, document indexing, search settings management, the useSearch model trait for automatic indexing, or search driver configuration. Covers @stacksjs/search-engine and config/search-engine.ts.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/stacksjs/stacks/blob/HEAD/.claude/skills/stacks-search-engine/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/stacks-search-engine, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Stacks Search Engine

Full-text search integration with Meilisearch and Algolia drivers.

Key Paths

  • Core package: storage/framework/core/search-engine/src/
  • Configuration: config/search-engine.ts

Search Driver Factory

import { useSearchEngine, useAlgolia, useMeilisearch } from '@stacksjs/search-engine'

const search = useSearchEngine()       // default driver
const algolia = useAlgolia()            // Algolia client
const meili = useMeilisearch()          // Meilisearch client

Document Operations

// Index documents
await search.addDocuments('products', [
  { id: 1, name: 'Widget', description: 'A useful widget', price: 29.99 },
  { id: 2, name: 'Gadget', description: 'A cool gadget', price: 49.99 }
])

// Search
const results = await search.search('products', 'widget')

// List indexes
const indexes = await search.listIndexes()

// Get/update settings
const settings = await search.getSettings('products')
await search.updateSettings('products', {
  searchableAttributes: ['name', 'description'],
  filterableAttributes: ['price', 'category'],
  sortableAttributes: ['price', 'created_at']
})

// Flush all documents
await search.flush('products')

Model Integration (useSearch Trait)

Models with useSearch trait are automatically indexed:

defineModel({
  name: 'Product',
  traits: {
    useSearch: {
      displayable: ['name', 'description', 'price'],
      searchable: ['name', 'description'],
      sortable: ['name', 'price', 'created_at'],
      filterable: ['category', 'status', 'price']
    }
  }
})

CLI Commands

buddy search-engine:update                    # index all searchable models
buddy search-engine:update --model Product    # index specific model
buddy search-engine:update --flush            # flush before re-indexing
buddy search-engine:update --settings         # update search settings only
buddy search-engine:settings                  # list current settings
buddy search-engine:settings --model Product  # settings for specific model

Driver Comparison

FeatureMeilisearchAlgolia
Self-hostedYesNo (cloud)
PricingFree (self-hosted)Per-search pricing
Typo toleranceBuilt-inBuilt-in
Faceted searchYesYes
Geo searchYesYes
SpeedVery fastVery fast

config/search-engine.ts

{ driver: 'opensearch' }  // 'meilisearch' | 'algolia' | 'opensearch'

Environment variables: MEILISEARCH_HOST, MEILISEARCH_KEY, SEARCH_ENGINE_DRIVER

Gotchas

  • Default driver is opensearch — configure in config or env
  • useSearch trait determines which model fields are indexed
  • displayable controls which fields appear in search results
  • searchable controls which fields are queried during search
  • filterable enables faceted filtering on those fields
  • sortable enables sorting by those fields
  • Use buddy search-engine:update --flush for full re-index
  • Meilisearch requires a running Meilisearch server
  • Algolia requires API keys from your Algolia dashboard
  • Settings updates don't re-index — run search-engine:update after changes