Typesense Laravel Package

Technical Evaluation

Architecture fit statamic-rad-pack/typesense is a glue package: it wires Statamic's flat-file content layer into Typesense as a search index. It sits at the boundary between the CMS (Statamic addon registration, Antlers/Blade templates, entry lifecycle events) and an external search service. For a Laravel/Statamic estate this is a natural fit — it avoids hand-rolling an indexer and keeps search configuration in version-controlled config rather than in ad-hoc Artisan commands. v3.3.1 does not change the architecture; it tightens the semantics of one method on the index abstraction.

Integration feasibility Low integration cost. Composer install, publish config, provide Typesense host/API key, define collections, and wire up Statamic's search driver. The package assumes a Typesense server is reachable — either self-hosted (container alongside the app) or Typesense Cloud. No first-party PHP SDK surprises; the package wraps the official client.

Technical risk The single change in v3.3.1 — "Make exists() a read-only check" (PR #39) — is small in surface area but is a behavioural change shipped under a patch version. Previously exists() plausibly performed an ensure-then-check (i.e. it could create or reconcile the collection schema as a side effect); it now only reports presence. Risks:

• Code paths that leaned on exists() as an implicit "create if missing" will now find a missing collection and, depending on downstream handling, either error or silently return empty results. Silent empty results are the worse failure mode for a search feature.
• The method name exists() strongly implied read-only all along, so the change is arguably a bug fix — but callers who observed the old behaviour may have built around it.
• Because the change is in the index layer rather than the Statamic-facing API, standard smoke tests (search returns results) will not catch it; only a fresh-environment provisioning run will.

Overall risk is low but non-zero, concentrated in bootstrap/provisioning flows rather than in steady-state querying.

Key questions

• Did any of our code, or any provisioning/CI script, call exists() expecting it to create the collection?
• Is collection creation now only reachable via an explicit command/action, and is that documented and in our deploy runbook?
• Does a missing collection fail loudly (exception) or degrade to empty search results?
• Is there a test in our suite that exercises a cold start against an empty Typesense instance?
• Why is a behaviour change shipping as a patch rather than a minor — is the maintainer treating the old behaviour as a defect?

Integration Approach

Stack fit Requires PHP 8.x and Laravel consistent with the Statamic version in use; the package tracks Statamic majors, so the binding constraint is Statamic's own upgrade cadence, not this package. Typesense server compatibility should be checked against the client version pinned in composer.json. Nothing here conflicts with a standard Laravel deployment topology (app containers + managed or sidecar Typesense).

Migration path For an existing install: composer update statamic-rad-pack/typesense to 3.3.1, then explicitly re-verify index provisioning on a non-production environment. The migration work is not code — it is confirming that whatever previously created collections still runs. If our bootstrap relied on exists(), replace that call with the package's explicit creation/import path or an Artisan reindex command before promoting. For a greenfield install, adopt 3.3.1 directly and document collection creation as a distinct deploy step.

Compatibility Patch release, no config or schema changes, no deprecations announced. Backwards compatible for read paths (search queries). The only compatibility question is the side-effect contract of exists(), which is effectively a narrow breaking change for a specific caller pattern.

Sequencing

1. Pin and upgrade in a staging environment with an empty Typesense instance (this is the step that surfaces the change).
2. Run the indexing/provisioning command and confirm collections are created explicitly.
3. Verify search returns expected results for representative content types.
4. Run the same cold-start check in production deploy as a one-off, since production already has collections and would otherwise mask the issue.
5. Only then treat 3.3.1 as the standard baseline across environments.

Operational Impact

Maintenance Minimal ongoing burden — one dependency bump plus a Typesense server to keep patched. The package is community-maintained (rad pack), single-maintainer-ish, with a small PR volume; that implies low churn but also limited bus factor. Pin the version and review changelogs rather than floating on ^3.

Support Upstream support is GitHub issues/PRs; no commercial SLA. Internal support burden is mainly "search returns nothing" triage, which requires someone who understands the Statamic-event-to-index pipeline. Worth nominating an owner.

Scaling Search is offloaded to Typesense, so app-tier scaling is largely decoupled from query load — a genuine operational win over database-backed search. Watch index size and reindex duration as content grows; full reindexes are the expensive operation, not steady-state queries.

Failure modes

• Missing collection after deploy — the specific risk introduced by 3.3.1 if provisioning depended on exists(). Symptom: empty results, no error.
• Typesense unreachable — search degrades; confirm the package fails gracefully and the rest of the site renders.
• Index drift — content updated while the indexer is down leaves stale results until a reindex; needs monitoring and a manual reindex path.
• Schema mismatch on upgrade — if collection fields change, an explicit recreate/reindex is required; the read-only exists() makes it more important that this is a deliberate step.

Ramp-up Low. A Laravel developer can be productive in under a day; the conceptual overhead is understanding Statamic's entry lifecycle events and how they map to index updates. Budget roughly half a day of team time to validate this release in staging, plus a short runbook entry documenting the explicit collection-creation step.