Statamic Peak Tools Laravel Package

Getting Started

This is not a standalone package. It is the shared Antlers layer of the Statamic Peak starter kit, extracted so that Peak and its child sites/starters can share the same tags, modifiers, and partials. Treat it as glue code for a Peak-based site, not as a general-purpose library you would pull into an arbitrary Statamic project.

Minimal path:

1. Scaffold or clone a Peak-based project. Peak already wires this in; you normally get it transitively.
2. If you are adding it to an existing Peak install, composer require studio1902/statamic-peak-tools and confirm the installed version aligns with your Peak branch (Peak 5/6/7 lines map to different Statamic majors).
3. Statamic auto-discovers the service provider — no manual config/app.php registration.
4. Look first at the repository's src/ directory (tag and modifier classes), then the README for the exact tag namespace, and finally Peak's own resources/views/ for how the tools are actually consumed. The tools only make sense in the context of Peak's view structure.
5. First real use case: you are building a Peak site and need the shared Antlers components/helpers (buttons, bard set partials, layout helpers) that Peak's templates call. Use them as-is rather than re-implementing.

If you are not on Peak, stop here. The cost of reverse-engineering the expected view paths and conventions almost always exceeds writing the few modifiers you actually need.

Implementation Patterns

Use it as the component layer, not a feature layer. The day-to-day value is calling the shared Antlers partials/tags from your own templates so your markup matches Peak's output. Build your page templates on top of those components instead of duplicating button, card, and bard markup.

Wrap Bard output centrally. The most common workflow is rendering a Bard field through the package's bard partials so that every set type (text, image, quote, video, etc.) has one canonical renderer. When a client asks for a new set type, you add one partial in your project and it is picked up everywhere the field is rendered — rather than editing each template.

Slot-based composition. Peak's components use Antlers slots ({{ slot }} / named slots). Pattern:

{{ partial:components/button variant="primary" }}
    Book now
{{ /partial:components/button }}

Keep your own project components in the same shape so they are interchangeable with the package's.

Modifier chains over custom PHP. For string/array formatting (URLs, class lists, responsive image data), prefer the package's modifiers plus core Statamic modifiers in a chain. Reach for a custom modifier only when the logic is genuinely domain-specific, and put it in your app, not in a fork of this package.

Extend via your own namespace, not by editing vendor. Register project-specific tags/modifiers in app/ and call them alongside the package's. Peak updates then flow through without merge conflicts.

Pair with Peak's config. Anything the tools read from config should be set in config/statamic/ (or Peak's own config files) in your project. Check the package source for which config keys it reads before overriding templates — a template override can silently bypass a config expectation.

Caching discipline. These are rendered on every request in a typical Peak setup. Use Statamic's static caching / half-measures, and avoid passing large collections into slot components when a cached partial would do.

Gotchas and Tips

• Version lockstep with Peak. The package's tags and partials assume a specific Peak view structure. A composer update on Peak without a matching tools version is the most likely source of "partial not found" or "undefined variable" errors. Pin both together and read the Peak upgrade guide, not just this repo's releases.
• Low bus factor, small surface. 11 stars and a niche GPL addon means limited external documentation and few Stack Overflow answers. Read the source — it is small — and budget for the possibility that you maintain a fork. GPL-3.0 also means distributed derivatives must stay GPL.
• Not a drop-in for non-Peak projects. The tools reference Peak's directory conventions (resources/views/components, bard partial sets). Installing it into a bare Statamic site produces missing-view errors that look like package bugs but are configuration mismatches.
• Antlers vs. Blade. Peak is Antlers-first. Mixing Blade components into a template that also uses these tools works, but debugging gets confusing — data passed into an Antlers partial is not automatically available inside a nested Blade component. Keep a single rendering style per template.
• Silent failures. Antlers tags that return empty output rarely throw. If a section renders blank, {{ dump }} the variable before the tag call, then check whether the tag expects a specific fieldtype shape (e.g., a Bard value object vs. a raw array). The mismatch is usually in the data, not the tag.
• Template overrides win quietly. Overriding a component partial in your project shadows the package version and will not receive upstream fixes. Keep a short list of overridden partials in the project README so future upgrades are auditable.
• Extension points are Statamic's, not the package's. There is no plugin API here; extend by registering your own tags/modifiers with Statamic's Statamic::tag() / modifier registry and composing alongside. Do not patch vendor/.
• Debugging tips. Enable Statamic's debug bar, set APP_DEBUG=true locally, and use {{ dump:var }}. For performance issues, time the partial in isolation — nested slot components are the usual culprit, not the package itself.
• When to skip it. If you need one or two helpers, copy the relevant modifier/tag into your app under MIT-compatible terms or reimplement it. The dependency is only worth it when you are genuinely living inside the Peak ecosystem.