JooTypesense

JooTypesense is a Joomla package that synchronizes Joomla content articles to Typesense collections.

The package provides:

• com_jootypesense: administrator UI for connection settings, collection mappings, remote status, frontend key generation, and manual reindexing.
• plg_system_jootypesense: runtime integration that creates/updates/deletes Typesense documents when Joomla articles change.
• plg_console_jootypesense: Joomla CLI command for full or per-collection reindexing.
• plg_task_jootypesense: Joomla Scheduler routine for recurring reindex jobs.

Requirements

• Joomla 4/5/6 compatible extension environment.
• PHP and Composer available for local package builds.
• A reachable Typesense server.
• A Typesense API key with permission to manage collections, keys, and documents.

Build

From the repository root:

./build.sh

The build script:

1. Reads the package version from VERSION.
2. Stages the component and plugins from src/.
3. Replaces {{VERSION}} placeholders in the staged Joomla manifests.
4. Runs composer install --no-dev inside the staged system plugin.
5. Creates individual extension ZIP files.
6. Creates the installable Joomla package:

dist/pkg_jootypesense.zip

Install dist/pkg_jootypesense.zip through Joomla's Extension Manager.

Generated files are intentionally ignored:

• build/
• dist/
• src/plugins/system/jootypesense/vendor/

Versioning and Releases

VERSION is the source of truth for release versions. Joomla manifest files use the {{VERSION}} placeholder in source and receive the concrete version only in the staged build output.

Development happens on develop. main is used only for publishing releases.

To release:

./release.sh

The release script:

1. Requires a clean worktree on develop.
2. Asks for patch, minor, or major.
3. Updates and commits VERSION on develop.
4. Merges develop into main.
5. Tags the main commit as vX.Y.Z.
6. Pushes develop, main, and the tag.

GitHub Actions runs automatically only for pushed v* tags, builds the package, and attaches dist/pkg_jootypesense.zip to the GitHub Release. The workflow can also be run manually to produce a build artifact without creating a release.

Configuration

After installation:

1. Enable the System - JooTypesense plugin.
2. Open the JooTypesense administrator component.
3. Configure the Typesense connection:
   • protocol
   • host
   • port
   • optional path prefix
   • API key
   • timeout
4. Create one or more collection mappings.

Each collection mapping connects a Joomla content category to a Typesense collection. A mapping can optionally include child categories.

Indexed Document Shape

JooTypesense indexes published Joomla articles into Typesense documents with standard article fields, including:

• id, title, alias, slug, state, language
• catid, category
• created, modified, created_ts, modified_ts
• introtext, fulltext, content
• images
• route, url, urls
• tags
• custom_fields

Custom fields are normalized before indexing. JSON-like custom field values are decoded so nested values can be indexed as Typesense objects.

Reindexing

Use the administrator UI, Joomla Scheduler, or Joomla CLI to rebuild documents.

Reindex all enabled mapped collections:

php cli/joomla.php jootypesense:reindex

Reindex one configured collection:

php cli/joomla.php jootypesense:reindex --collection=collection_name

The command returns a non-zero exit code when indexing failures are reported.

Runtime Behavior

When enabled, the system plugin listens to Joomla content events:

• article save: upserts published mapped articles
• article delete: removes the document from mapped collections
• article state change: indexes published articles and removes unpublished ones
• category changes: cleans up stale documents from the previous mapped collection

The plugin ensures configured Typesense collections exist before indexing. It can also update collection fields when the configured schema changes.

Development

Source files live under src/ using the same paths they have after Joomla installation.

Useful entry points:

• src/administrator/components/com_jootypesense/
• src/plugins/system/jootypesense/src/Extension/JooTypesense.php
• src/plugins/system/jootypesense/src/Service/ArticleIndexer.php
• src/plugins/system/jootypesense/src/Service/TypesenseManager.php
• src/plugins/console/jootypesense/src/Command/ReindexCommand.php
• src/plugins/task/jootypesense/src/Extension/JooTypesenseTaskPlugin.php

Keep Composer dependencies for the system plugin declared in:

src/plugins/system/jootypesense/composer.json