PayloadCMS + Typesense Plugin

Forked from FrontTribe’s Typesense Search Plugin, Rubix Studios implementation has been substantially re-engineered to meet stricter production, deployment, and TypeScript standards. The codebase has been streamlined for improved maintainability, enhanced type safety, and predictable behaviour under load, while preserving full compatibility with Payload CMS and Typesense.

The fork introduces meaningful architectural improvements, including more efficient caching strategies with race-condition mitigation, improved request handling, and deployment-safe defaults. The result is a lighter, more resilient integration.

With a modular, tree-shakable structure and optional support for advanced search capabilities such as vector-based querying, the plugin is designed to scale from simple content search implementations to more complex, search-driven applications without unnecessary bloat.

This project is actively maintained by Rubix Studios and is intended for production environments where performance, stability, and code quality are critical.

PayloadCMS + Typesense Plugin

FrontTribe's Typesense Search Plugin

!Release

Installation

``sh
pnpm add @rubixstudios/payload-typesense
`

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

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: '📝',
syncLimit: 500, // Overrides the default sync limit of 1000
},
},
// This feature is experimental
vectorSearch: {
enabled: true, // Enables vector-based semantic search
embedFrom: ['title', 'content'], // Omit to fall back to collection searchFields
embeddingModel: 'ts/all-MiniLM-L12-v2',
},
}),
],
})
`

`tsx
import { HeadlessSearchInput } from '@rubixstudios/payload-typesense'

export function GlobalSearchPage() {
return (
baseUrl="http://localhost:3000"
theme="modern" // Available themes: "modern" | "dark"
placeholder="Search everything..."
onResultClick={(result) => {
console.log('Selected document:', result.document)
}}
/>
)
}

export function CollectionSearch() {
return (
baseUrl="http://localhost:3000"
collections={['posts', 'products']}
placeholder="Search posts and products..."
onResultClick={(result) => {
console.log('Selected document:', result.document)
}}
/>
)
}

export function VectorSearch() {
return (
baseUrl="http://localhost:3000"
vector={true} // Vector search enabled
collections={['posts', 'products']}
placeholder="Search posts and products..."
onResultClick={(result) => {
console.log('Selected document:', result.document)
}}
/>
)
}
`

Features

- Performance
Sub-millisecond search responses with optimized request handling.
- Flexible Search
Single-collection, multi-collection, or universal search using one component.
- Vector Search
Optional semantic search using embeddings, with graceful fallback to keyword search.
- Modern UI
Headless, responsive implementation compatible with Tailwind CSS.
- Real-Time Synchronisation
Continuous indexing and sync with Payload CMS.
- Efficient Caching
In-memory caching with configurable TTL and race-condition safeguards.
- Production Ready
Robust error handling, deployment-safe defaults, and platform compatibility.
- Tree-Shakable Architecture
Modular design enabling smaller bundles and selective feature usage.

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:
- 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

Themes

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

$3

`tsx
// Modern theme (default)


// Dark theme

`

$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

- 2 Pre-built Themes: Modern, Dark
- 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

Production

- Race Condition Protection: ensureCollection` prevents startup crashes
- Type Safety: Proper Payload CMS types prevent runtime errors
- Document Validation: Filters malformed data before sync
- Graceful Degradation: Silent failures don't break Payload operations

Developer

- Smaller Components: Easier to understand and maintain
- Maintainable: Single Responsibility Principle enforced
- Well-Documented: Clear separation of concerns

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support or inquiries:

- LinkedIn: rubixvi
- Website: Rubix Studios

Author

Rubix Studios Pty. Ltd.
https://rubixstudios.com.au

Acknowledgments

- FrontTribe