Skip to content

run-as-root/typesense-magento2

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
README.md
README.md
 
 

Repository files navigation

Typesense Integration Guide for Magento 2 / Adobe Commerce

A comprehensive guide for implementing fast, typo-tolerant search using Typesense with Magento 2 and Adobe Commerce, including Hyvä theme compatibility.

Typesense + Magento Magento 2 Hyvä

🚀 Overview

Typesense is a modern, developer-friendly search engine that delivers sub-50ms search results with advanced features like typo tolerance, faceted search, and intelligent ranking. This integration provides a powerful alternative to Elasticsearch, Algolia, and default Magento search functionality.

Why Choose Typesense?

  • ⚡ Lightning Fast: Sub-50ms search response times
  • 🧠 Intelligent: Machine learning-powered with typo tolerance
  • 💰 Cost-Effective: Especially with self-hosting options
  • 👨‍💻 Developer-Friendly: Simple API and intuitive configuration
  • 🔧 Easy Maintenance: Minimal operational overhead compared to Elasticsearch

🛠 Required Tools & Extensions

Core Extensions (Ceymox)

1. Typesense Search - Magento Extension

  • Purpose: Base Typesense integration for standard Magento themes
  • Price: $49.00
  • Source: Ceymox Typesense Magento Extension
  • Key Features:
    • Instant, typo-tolerant search results
    • Keyword-specific filtering
    • Advanced search facets
    • RESTful API integration

2. Typesense Search - Hyvä Module

  • Purpose: Enhanced Typesense integration optimized for Hyvä themes
  • Price: $149.00
  • Source: Ceymox Typesense Hyvä Module
  • Key Features:
    • Full Hyvä theme compatibility
    • Advanced grouping and sorting
    • Alpine.js integration
    • Tailwind CSS styling support

🏗 Architecture & Data Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           TYPESENSE MAGENTO 2 ARCHITECTURE                  │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐    ┌─────────────────┐    ┌──────────────────────────────┐
│   MAGENTO 2     │    │   TYPESENSE     │    │      DEPLOYMENT OPTIONS      │
│   FRONTEND      │    │   EXTENSIONS    │    │                              │
│                 │    │                 │    │  ┌─────────────────────────┐ │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │  │   OPTION 1: CLOUD       │ │
│ │Search Field │ │    │ │   Base      │ │    │  │                         │ │
│ │Autocomplete │◄┼────┼►│ Extension   │ │    │  │ ┌─────────────────────┐ │ │
│ │Results Page │ │    │ │             │ │    │  │ │  Typesense Cloud    │ │ │
│ └─────────────┘ │    │ └─────────────┘ │    │  │ │  - Managed Service  │ │ │
│                 │    │ ┌─────────────┐ │    │  │ │  - Auto Scaling     │ │ │
│ ┌─────────────┐ │    │ │   Hyvä      │ │    │  │ │  - 24/7 Support     │ │ │
│ │Hyvä Theme   │ │    │ │  Module     │ │    │  │ └─────────────────────┘ │ │
│ │Components   │◄┼────┼►│ (Optional)  │ │    │  │                         │ │
│ └─────────────┘ │    │ └─────────────┘ │    │  └─────────────────────────┘ │
└─────────────────┘    └─────────────────┘    │                              │
         │                       │            │  ┌─────────────────────────┐ │
         │                       │            │  │   OPTION 2: SELF-HOST   │ │
         ▼                       ▼            │  │                         │ │
┌─────────────────────────────────────────┐   │  │ ┌─────────────────────┐ │ │
│             DATA FLOW                   │   │  │ │  Your Server +      │ │ │
│                                         │   │  │ │  Proxy Setup        │ │ │
│  ┌─────────────┐  ┌─────────────────┐   │   │  │ │  - Custom Config    │ │ │
│  │   Magento   │  │    Typesense    │   │   │  │ │  - Full Control     │ │ │
│  │  Database   │  │   Collections   │   │   │  │ │  - Cost Effective   │ │ │
│  │             │  │                 │   │   │  │ └─────────────────────┘ │ │
│  │ ┌─────────┐ │  │ ┌─────────────┐ │   │   │  │                         │ │
│  │ │Product  │ │  │ │  products   │ │   │   │  └─────────────────────────┘ │
│  │ │Category │►┼─►│ │ categories  │ │   │   └──────────────────────────────┘
│  │ │CMS Page │ │  │ │    pages    │ │   │
│  │ │         │ │  │ │ suggestions │ │   │
│  │ └─────────┘ │  │ └─────────────┘ │   │
│  └─────────────┘  └─────────────────┘   │
│                                         │
│  Indexing Process:                      │
│  php bin/magento indexer:reindex        │
│  ├── typesense_products                 │
│  ├── typesense_categories               │
│  ├── typsense_pages                     │
│  └── suggestions                        │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                            USER SEARCH JOURNEY                              │
└─────────────────────────────────────────────────────────────────────────────┘

User Types → Frontend Processes → Typesense API → Results Display
     │              │                    │              │
     ▼              ▼                    ▼              ▼
┌─────────┐  ┌──────────────┐  ┌─────────────────┐  ┌──────────┐
│ "shirt" │  │ Autocomplete │  │ Search Request  │  │ Instant  │
│ "shrit" │─►│ Suggestions  │─►│ + Typo Fix      │─►│ Results  │
│ "shurt" │  │ (Visual      │  │ + Facet Filter  │  │ < 50ms   │
└─────────┘  │  Facade)     │  │ + Ranking       │  └──────────┘
             └──────────────┘  └─────────────────┘

📋 Deployment Solutions

Solution 1: Typesense Cloud (Managed Service)

Best for: Production environments, teams preferring managed infrastructure

  • Pricing: Pay-per-use model - Calculate costs
  • Benefits:
    • ✅ Zero maintenance overhead
    • ✅ Automatic scaling and backups
    • ✅ Global CDN and multi-region support
    • ✅ 24/7 professional support
    • ✅ SSL/TLS encryption included
  • Setup: Simple API key configuration

Solution 2: Self-Hosted with Proxy (Cost-Effective)

Best for: Budget-conscious projects, custom requirements, data sovereignty needs

  • Cost: Free Typesense license + your server costs
  • Benefits:
    • ✅ Complete control over infrastructure
    • ✅ Custom configurations possible
    • ✅ No per-search pricing
    • ✅ Data stays on your servers
  • Requirements:
    • Your own server infrastructure
    • Proxy configuration for API communication
    • Manual maintenance and updates
  • Installation Guide: Typesense Self-Hosting Documentation

Recommendation: 2 CPUs, 3 GB RAM with maxcluster's professional hosting

🔧 Step-by-Step Integration Guide

Step 1: Install Extensions

Installation guideline

Step 2: Configure Typesense Backend

For Cloud Deployment:

  1. Register at Typesense Cloud
  2. Create cluster and obtain API credentials
  3. Note your cluster URL and API key

For Self-Hosted Deployment:

  1. Install Typesense on your server
  2. Configure proxy server for API communication
  3. Set up security and firewall rules

Step 3: Configure Magento Admin

Navigate to: Admin Panel > Stores > Configuration > Typesense Search > General

Configuration Settings:

  • Enable Search: Yes
  • Search-only (public) API key: Your Typesense API Key
  • Cloud Key:
    • Cloud: Use your actual API key
    • Self-hosted: Any random value (required by extension)
  • Index Name Prefix: Unique identifier for your store
  • Nodes: Your Typesense endpoint
  • protocol: https
  • Port: 443
# Save and refresh configuration
php bin/magento cache:flush
php bin/magento cache:clean config

Step 4: Index Your Data

# Index all search data to Typesense
php bin/magento indexer:reindex typesense_categories typesense_products typsense_pages suggestions

Note: Indexing time depends on catalog size. Monitor progress and ensure adequate server resources.

Step 5: Verification & Testing

  • ✅ Verify Typesense collections are created
  • ✅ Test frontend search functionality
  • ✅ Confirm autocomplete suggestions work
  • ✅ Test faceted search and filtering
  • ✅ Validate typo tolerance features

⚠️ Known Issues & Solutions

Issue 1: Broken Search Layout

Problem: Search results page layout breaks when using Magento's default search page instead of Typesense's custom layout.

Root Cause: Extension overrides default Magento search layouts.

Solution: Create layout overrides in your theme to revert to default Magento 2 state.

<!-- Example layout override -->
<!-- app/design/frontend/[Vendor]/[Theme]/Ceymox_TypesenseSearch/layout/override/base/catalogsearch_result_index.xml -->
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <body>
        <!--        <referenceBlock name="breadcrumbs" remove="true" />-->
<!--        <referenceBlock name="page.main.title" display="false"/>-->
<!--        <referenceContainer name="columns.top">-->
<!--            <block ifconfig="typesense_search_result/instant_search_result/enable_result_page" class="Magento\Framework\View\Element\Template" name="typesense.loader" template="Ceymox_TypesenseSearch::loader.phtml" />-->
<!--        </referenceContainer>-->
<!--        <move element="catalog.compare.sidebar" destination="sidebar.main" />-->
<!--        <move element="wishlist_sidebar" destination="sidebar.main" />-->
<!--         <referenceBlock name="search.result">-->
<!--            <action ifconfig="typesense_search_result/instant_search_result/enable_result_page" method="setTemplate">-->
<!--                <argument name="template" xsi:type="string">Ceymox_TypesenseSearch::search/result.phtml</argument>-->
<!--            </action>-->
<!--        </referenceBlock> -->
<!--        <referenceBlock name="catalogsearch.leftnav">-->
<!--            <action ifconfig="typesense_search_result/instant_search_result/enable_result_page" method="setTemplate">-->
<!--                <argument name="template" xsi:type="string">Ceymox_TypesenseSearch::search/layer/view.phtml</argument>-->
<!--            </action>-->
<!--            <arguments>-->
<!--                <argument name="view_model"-->
<!--                        xsi:type="object">Ceymox\TypesenseSearch\ViewModel\General</argument>-->
<!--            </arguments>-->
<!--        </referenceBlock>-->
    </body>
</page>

Issue 2: Performance Impact

Problem: Typesense scripts loading on every page can impact initial page load performance.

Root Cause: JavaScript libraries loaded regardless of search usage.

Solution: Implement visual facade pattern - load Typesense scripts only when search functionality is actively used.

Implementation Strategy:

  1. Create lightweight placeholder for search field
  2. Load full Typesense functionality on first search interaction
  3. Use lazy loading for autocomplete suggestions
  4. Implement proper caching strategies

🚀 Performance Optimization Best Practices

Frontend Optimization

  • Visual Facade: Load search scripts only when needed
  • Lazy Loading: Implement progressive loading for search suggestions
  • Caching: Leverage browser caching for search assets
  • Debouncing: Limit API calls during rapid typing

Backend Optimization

  • Indexing Strategy: Schedule reindexing during low-traffic periods
  • Memory Management: Allocate sufficient PHP memory for indexing
  • Database Optimization: Ensure proper indexing on source tables
  • Monitoring: Set up performance monitoring and alerting

Infrastructure Optimization

  • CDN: Use content delivery networks for static assets
  • Caching Layers: Implement Redis/Varnish for full-page caching
  • Server Resources: Optimize CPU and memory allocation
  • Load Balancing: Distribute traffic across multiple instances

🔍 Troubleshooting Guide

Diagnostic Commands

# Check indexer status
php bin/magento indexer:status

# Reset and reindex specific indexers
php bin/magento indexer:reset typesense_products
php bin/magento indexer:reindex typesense_products

# Monitor logs
tail -f var/log/typesense.log
tail -f var/log/system.log
tail -f var/log/debug.log

Common Issues & Fixes

Issue Symptoms Solution
No Search Results Empty search results despite indexed data Check API credentials and server connectivity
Slow Indexing Indexing process times out or fails Increase PHP memory_limit and max_execution_time
Layout Problems Search page displays incorrectly Override extension layout files
Autocomplete Not Working No suggestions appear Verify JavaScript loading and API responses
Performance Issues Slow page load times Implement lazy loading and caching

📚 Resources & Support

Official Documentation

Community & Support

  • Ceymox Support: Available through their official website
  • Typesense Community: GitHub discussions and Discord
  • Magento Community: Stack Exchange, Forums, GitHub

Professional Services

For complex implementations or custom development needs, consider engaging:

  • Certified Magento developers with Typesense experience
  • Ceymox professional services team
  • Specialized e-commerce agencies

📄 License & Legal

  • Extension licenses governed by Ceymox terms and conditions
  • Typesense follows Apache 2.0 license for open-source version
  • This documentation provided under MIT license
  • Please review individual component licenses before production use

🎯 Quick Start Checklist

  • Purchase required Ceymox extensions
  • Choose deployment method (Cloud vs Self-hosted)
  • Install and configure extensions
  • Set up Typesense backend infrastructure
  • Configure Magento admin settings
  • Run initial data indexing
  • Test search functionality thoroughly
  • Implement performance optimizations
  • Monitor and maintain system health

Happy Searching! 🔍

Last Updated: 2025 | For the latest updates and advanced configuration options, refer to the official Ceymox documentation and Typesense guides.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •