Typesense Search Plugin for Payload CMS

A powerful, production-ready search plugin that integrates Typesense with Payload CMS, providing lightning-fast, typo-tolerant search capabilities with real-time synchronization.

📋 Prerequisites

- Node.js: 22.19.0+ or 20.9.0+
- Payload CMS: 3.64.0+
- Typesense: 0.25.2+
- pnpm (recommended) or npm/yarn

🚀 Quick Start

``bash


1. Install the plugin

pnpm add typesense-search-plugin

2. Start Typesense

docker run -p 8108:8108 -v/tmp/typesense-data:/data typesense/typesense:0.25.2 --data-dir /data --api-key=xyz --enable-cors

3. Add to your Payload config

`

`typescript
// payload.config.ts
import { buildConfig } from 'payload/config'
import { typesenseSearch } from 'typesense-search-plugin'

export default buildConfig({
plugins: [
typesenseSearch({
typesense: {
apiKey: 'xyz',
nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
},
collections: {
posts: {
enabled: true,
searchFields: ['title', 'content'],
facetFields: ['category', 'status'],
displayName: 'Blog Posts',
icon: '📝',
},
},
}),
],
})
`

`tsx
// 4. Use the search component
import { HeadlessSearchInput } from 'typesense-search-plugin'

function SearchPage() {
return (
baseUrl="http://localhost:3000"
theme="modern" // Choose from: modern, minimal, elegant, dark, colorful
placeholder="Search everything..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}

// Multi-collection search
function MultiCollectionSearch() {
return (
baseUrl="http://localhost:3000"
collections={['posts', 'products']}
placeholder="Search posts & products..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}

// Single collection search
function PostSearch() {
return (
baseUrl="http://localhost:3000"
collection="posts"
placeholder="Search posts..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}
`

✨ Features

- ⚡ Lightning Fast: Sub-millisecond search response times
- 🔍 Flexible Search: Single, multiple, or universal collection search with one component
- 🎨 Modern UI: Beautiful, responsive design with Tailwind CSS
- 🎯 Smart API Selection: Automatically chooses optimal endpoint for performance
- 🔄 Real-time Sync: Automatic synchronization with Payload CMS
- 💾 Built-in Caching: In-memory cache with configurable TTL
- 🛡️ Production Ready: Comprehensive error handling and performance optimization
- 📱 Responsive: Mobile-first design that works on all devices

📚 Documentation

For detailed documentation, visit our comprehensive docs:

- Getting Started
- Installation Guide
- Configuration
- API Reference
- Components
- Customization
- Performance
- Troubleshooting

🔧 API Endpoints

- GET /api/search - Universal search across all collections
- GET /api/search/{collection} - Search specific collection
- POST /api/search/{collection} - Advanced search with filters
- GET /api/search/{collection}/suggest - Search suggestions
- GET /api/search/collections - Collection metadata
- GET /api/search/health - Health check

🎨 Components

- HeadlessSearchInput - Single component supporting all search patterns:
- Single Collection: collection="posts" - Direct API calls for optimal performance
- Multiple Collections: collections={['posts', 'products']} - Smart filtering with universal search
- Universal Search: No collection props - Search across all collections
- Complete UI Control: Customizable rendering with comprehensive theme system

🎨 Theme System

The plugin includes a powerful theme system with 5 pre-built themes and unlimited customization:

$3

`tsx
// Modern theme (default) - Clean and professional


// Minimal theme - Flat design with minimal styling


// Elegant theme - Sophisticated with gradients


// Dark theme - Perfect for dark mode


// Colorful theme - Vibrant and modern

`

$3

`tsx
const customTheme = {
theme: 'modern',
colors: {
inputBorderFocus: '#10b981',
inputBackground: '#f0fdf4',
resultsBackground: '#f0fdf4',
},
spacing: {
inputPadding: '1rem 1.25rem',
inputBorderRadius: '1.5rem',
},
enableAnimations: true,
enableShadows: true,
}


``

$3

- 5 Pre-built Themes: Modern, Minimal, Elegant, Dark, Colorful
- Unlimited Customization: Override any color, spacing, typography, or animation
- Performance Options: Disable animations/shadows for better performance
- Responsive Design: Automatic mobile optimization
- CSS Variables: Advanced styling with CSS custom properties
- TypeScript Support: Full type safety for all theme configurations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

- Typesense for the amazing search engine
- Payload CMS for the flexible headless CMS