Tagixo Docs
Back to Website Start Here

Setup

Installation

Install ccast/tagixo-filament, publish assets, and verify the baseline.

8 min read Route: /documentation/filament/installation

Installing the Tagixo Filament SDK

This guide covers installing ccast/tagixo-filament into an existing Filament v5 application that already has ccast/tagixo (the core package) running.

1. Prerequisites

Before installing, confirm every item in the table below is satisfied.

Requirement Minimum version Notes
PHP 8.2 8.3 recommended
Filament 5.x v4 and below are not supported
ccast/tagixo (core) same minor as SDK Install and configure core first
Laravel 11.x 12.x also supported
Database any Laravel-supported PostgreSQL recommended for production

The Filament SDK is a thin integration layer on top of the core package. The core must be installed, its migrations run, and its service provider registered before you proceed.

2. Requiring the package

ccast/tagixo-filament is published on public Packagist. No GitHub token or private repository configuration is required.

composer require ccast/tagixo-filament

Laravel's package auto-discovery registers the service provider automatically. You do not need to add anything to config/app.php.

After the package installs, confirm discovery succeeded:

php artisan package:discover --ansi

You should see Ccast\TagixoFilament\TagixoFilamentServiceProvider listed in the output.

3. Publishing assets

Assets are published from the core package (ccast/tagixo), not from the Filament SDK. The SDK reads the files that core publishes.

php artisan vendor:publish --tag=tagixo-assets --force

The --force flag overwrites any previously published files with the current version. Always use it when upgrading either package.

4. What is published

The command above copies a pre-built front-end bundle into your application's public/ directory:

public/vendor/tagixo/
├── builder.js          # main ES-module bundle (the visual builder)
├── builder.css         # all builder styles (includes PrimeVue, Tiptap, SortableJS)
├── fonts/              # icon fonts referenced by builder.css
└── chunks/             # code-split ES modules lazy-loaded by builder.js

These files are the entire front-end surface of the builder. Nothing else needs to be compiled or bundled by your application.

5. No Vite or npm step required

The bundle shipped by ccast/tagixo is already compiled and minified. Your application does not need to:

  • run npm install or npm run build for the builder to work
  • add any Vite config entries
  • call @vite() or @viteReactRefresh() in the builder layout
  • maintain a vite.config.js manifest entry for the builder

If your application already uses Vite for its own assets (e.g. a custom admin theme), those pipelines are independent and unaffected.

Important — type="module" and query-string cache-busting: builder.js is loaded as an ES module. Do not append a ?v= query string to the <script src> tag. Browsers treat a module URL with a different query string as a distinct module graph, which causes Pinia (and other singletons) to be instantiated twice, breaking the builder state. Cache-busting for the builder bundle is handled by publishing a new file on upgrade.

6. The Blade layout

The Filament SDK ships a dedicated Blade layout used by the builder page. It is referenced in your Filament resource or page as:

protected static string $view = 'tagixo-filament::layout';

What the layout includes

Included asset How
public/vendor/tagixo/builder.css <link rel="stylesheet"> in <head>
public/vendor/tagixo/builder.js <script type="module"> before </body>
Filament's own styles/scripts via @filamentStyles / @filamentScripts hooks
Dynamic per-page styles injected by the builder <style id="vb-dynamic-styles"> placeholder kept after builder.css

The <script type="module"> warning

Filament's asset pipeline may emit a browser console warning along the lines of:

Scripts with type="module" are deferred by default.

This is expected behaviour. The builder initialises inside a DOMContentLoaded listener and does not rely on synchronous script execution. The warning can be safely ignored.

7. Version compatibility matrix

SDK (ccast/tagixo-filament) Core (ccast/tagixo) Filament PHP
1.0.x 1.0.x 5.x 8.2 / 8.3

When upgrading, keep the SDK and core minor versions in sync. Mismatched minor versions may result in builder JS calling PHP endpoints that do not exist, or PHP returning payloads the JS does not understand.

8. Verifying the installation

Follow these four steps after installing.

Step 1 — Check published files

ls -lh public/vendor/tagixo/

You should see builder.js, builder.css, a fonts/ directory, and a chunks/ directory.

Step 2 — Check routes

php artisan route:list --path=tagixo

Tagixo's internal API routes (bootstrap, page data, save, media, etc.) must appear. If the list is empty, the core service provider did not register correctly — re-run php artisan package:discover.

Step 3 — Visit the builder page

Open the Filament admin panel in your browser and navigate to a page that uses the builder. The visual builder canvas should render inside the Filament layout. If you see a blank panel area, open the browser console and check for errors (see Troubleshooting below).

Step 4 — Check the network tab

In browser DevTools -> Network, filter by tagixo. You should see:

Request Expected status
GET /vendor/tagixo/builder.js 200
GET /vendor/tagixo/builder.css 200
GET /tagixo/builder/bootstrap 200
GET /tagixo/builder/page/{id} 200

Console message reference

Console message Meaning
[Tagixo] Builder initialised Successful mount
[Tagixo] Plugin registry loaded — N plugins Core plugin system ready
[Tagixo] Form helper classes registered Form module CSS injected
[Tagixo] WARN: no layout found No default layout seeded yet

9. Re-publishing assets after upgrades

Every time you upgrade ccast/tagixo or ccast/tagixo-filament, re-publish the assets:

composer update ccast/tagixo ccast/tagixo-filament
php artisan vendor:publish --tag=tagixo-assets --force

Octane applications

If your application runs Laravel Octane, reload the worker after publishing:

php artisan octane:reload

Octane caches resolved file paths in memory. Without a reload, the worker may serve stale asset paths from the previous publish.

Docker / containerised deployments

In containerised environments the public/vendor/tagixo/ directory must be committed to source control (or copied into the image at build time) because vendor:publish cannot run at container start without composer dev-dependencies. The standard workflow is:

  1. Run vendor:publish --tag=tagixo-assets --force locally after upgrading.
  2. Commit the updated files in public/vendor/tagixo/.
  3. Build and push the new image.

10. Troubleshooting

builder.js returns 404

  • Confirm you ran vendor:publish --tag=tagixo-assets --force.
  • Confirm public/vendor/tagixo/builder.js exists on disk.
  • In containerised deployments, confirm the file was committed and is present in the running container (docker exec <container> ls public/vendor/tagixo/).
  • Check that your web server (nginx, Apache) serves the public/ directory and has no deny rule for vendor/.

Wrong layout / builder renders outside Filament chrome

  • Confirm your Filament resource or page sets protected static string $view = 'tagixo-filament::layout'.
  • Run php artisan view:clear to flush any cached compiled views.

Plugin not found / [Tagixo] Plugin registry: 0 plugins

  • The core service provider (Ccast\Tagixo\TagixoServiceProvider) must register before the Filament SDK provider. Check php artisan package:discover output for ordering issues.
  • Confirm ccast/tagixo is listed in composer.json and installed.

401 / 403 on /tagixo/builder/bootstrap

  • The bootstrap endpoint requires an authenticated Filament session. Confirm you are logged in to the admin panel.
  • If using a custom auth guard in Filament, ensure Tagixo's middleware group allows that guard.

Missing form helper classes (form fields unstyled)

  • The form helper CSS is injected by a render hook registered by the core service provider. If fields appear unstyled, confirm the service provider is loaded and that your Filament panel calls ->renderHook() without stripping third-party hooks.
  • Run php artisan optimize:clear to clear config and route caches, then reload.