Statamic Bard Text Align Laravel Package

Getting Started

1. Install the addon

   composer require optimoapps/statamic-bard-text-align
   

   It's a Statamic addon, so it auto-registers via Laravel package discovery — no manual providers entry needed in config/app.php in a modern Statamic install.

2. Where to look first

   • README.md — usually documents the exact toolbar button names and any config keys.
   • src/ServiceProvider.php — tells you how the addon hooks in: whether it registers Bard buttons via Bard::buttons([...]), injects JS/CSS via Statamic::script()/Statamic::style(), or ships a published config.
   • resources/js/ (or public/js/) — the TipTap/ProseMirror extension that provides the textAlign marks.
   • config/ — if a config file ships, publish it: php artisan vendor:publish --tag=statamic-bard-text-align-config.

3. First use case — enable alignment on a Bard field Open the fieldset containing your Bard field (e.g. resources/fieldsets/content.yaml) and add the addon's toolbar buttons to the buttons array:

   -
     handle: content
     field:
       type: bard
       buttons:
         - bold
         - italic
         - align_left
         - align_center
         - align_right
   

   The exact button handles are defined by the addon (check the README); the typical naming is align_left / align_center / align_right / align_justify.

4. Build / clear caches

   php artisan cache:clear
   php artisan statamic:stache:clear
   

   Then hard-refresh the CP. Because Bard is a TipTap editor, the JS extension must load in the Control Panel — if you've customised composer.json post-autoload-dump scripts or disabled package discovery, the JS may never reach the browser.

5. Verify it renders on the frontend — publish a post with a centered paragraph, then {{ content }} in your Antlers template and inspect the HTML. You should see a <p class="text-center"> (or style="text-align:center;" — check what the extension emits).

Implementation Patterns

Pattern 1 — Add to an existing Bard fieldset Most day-to-day use is just adding the alignment buttons to the buttons: array of a Bard field you already have. This is the safest and most common integration: it only enables alignment where you want it (e.g. on a "Page Hero" field but not on a "Sidebar Note" field).

Pattern 2 — Enable globally via a reusable fieldset Create resources/fieldsets/_bard-default.yaml with your standard button set including align buttons, then import it into every Bard field. This keeps toolbar configuration DRY across the site and makes it trivial to add align buttons everywhere the addon is useful.

Pattern 3 — Pair with a CSS layer for the frontend The editor only marks alignment; it does not style your site. Add explicit CSS so the rendered output matches what editors see:

.text-left   { text-align: left; }
.text-center { text-align: center; }
.text-right  { text-align: right; }
.text-justify{ text-align: justify; }

If the addon emits inline style="text-align:…" instead of classes, you can skip this — but verify by inspecting saved HTML.

Pattern 4 — Scope alignment to specific content types Add the buttons only to fields that feed into layouts where alignment is meaningful (hero sections, callouts, long-form pages). For structured content rendered inside <p>-constrained components, alignment can look broken; scoping avoids the temptation for editors to center-align body copy.

Pattern 5 — Combine with the Marks/Buttons pipeline Because this addon extends Bard's toolbar, it composes naturally with other Bard button addons (Bard Link, Bard Image, color, etc.). Configure the full button ordering in the fieldset rather than relying on defaults — TipTap buttons render in the order configured.

Integration tip — control panel and content pipeline

• Control Panel: the JS extension runs only in the CP; it will be silently absent if your addon assets aren't compiled/published. Confirm by opening DevTools → Sources and looking for the addon's JS bundle after loading a Bard field.
• Content pipeline: if you use the REST API or Statamic::tag('collection'), the alignment markup is just part of the HTML field. If you sanitise HTML (e.g. with mews/purifier or a custom cleaner), confirm class/style are allowed on <p>, <h2>, etc., otherwise the alignment is stripped after save.

Gotchas and Tips

• Assets are cached aggressively. After installing or upgrading, run php artisan statamic:stache:clear and a hard browser refresh (Cmd/Ctrl+Shift+R). The CP bundle is fingerprinted, but the addon's published JS under public/vendor/... is not — stale copies are a common "nothing happens" cause.
• Not a Markdown field addon. This only affects Bard (TipTap/ProseMirror). Markdown fields won't show the buttons.
• Editor-only styling. The alignment applies visually in the CP via TipTap, but your frontend has no styling by default. Editors will report "it doesn't work" when it's actually a missing CSS class in your theme. Document the expected class names for your team.
• Version compatibility. Check the composer.json constraints against your Statamic major version. Bard's extension API changed across Statamic 3.x → 4.x → 5.x. If the addon hasn't been updated for your version, the TipTap extension may fail silently or throw a JS error in the console that only disables the toolbar buttons (no PHP exception).
• Zero stars ≠ broken, but it does mean no community safety net. With 0 stars and 0 dependents, budget time to read the source yourself. Fork it if you need to patch: it's a small, single-purpose addon, so the code surface is manageable.
• Debugging checklist when a button does nothing: (1) DevTools Console — look for TipTap "extension not found" errors; (2) confirm the button handle in your fieldset matches the README exactly — a typo silently omits the button; (3) confirm the JS bundle is loaded on the page; (4) confirm you cleared caches; (5) confirm you're using Bard, not Markdown.
• Extension points to expect. Small addons usually expose one of: a published config file with the list of alignment options, a Bard::buttons() registration you can override in a service provider, or a Statamic::script() call you can replace with your own bundled version. Look in src/ServiceProvider.php — if it calls Statamic::booted() and registers buttons, you can generally override the button list in your own AppServiceProvider without forking.
• TipTap alignment and HTML output. Some versions emit classes, some emit inline styles. If you're migrating content between this addon and a raw TipTap @tiptap/extension-text-align setup (e.g. for a Nuxt/Inertia editor), make sure the types and alignments options match, otherwise alignment won't survive the round-trip.
• Upgrade path. Because the addon is small and low-adoption, pin it in composer.json ("optimoapps/statamic-bard-text-align": "^1.0") and review the source on each Statamic major upgrade rather than trusting composer update alone. Keep a one-line fallback in your own app (a tiny custom Bard extension using @tiptap/extension-text-align) so you can drop the dependency if it goes unmaintained.