Jack McDade

Overview of Maintainable Statamic Development Building a website is easy; maintaining it for three years is where the real challenge lies. In the ecosystem of Laravel, Statamic stands out as a unique hybrid CMS—balancing the speed of flat-file storage with the power of a dynamic framework. This guide focuses on building sites that don't just work on launch day but remain easy to update, scale, and support through architectural best practices. By embracing "The Statamic Way," developers can create highly composable interfaces that empower clients while maintaining strict design integrity. We will explore how to use fieldsets for global consistency, implement a robust "Page Builder" using replicator sets, and organize Antlers templates to prevent the dreaded "spaghetti view" folder. Prerequisites To follow this tutorial, you should have a baseline understanding of: - **PHP & Laravel Basics**: Understanding how Laravel structures its directories and handles logic. - **Statamic Fundamentals**: Knowledge of Entries, Collections, and Blueprints. - **Tailwind CSS**: Used for the styling examples in our components. - **Antlers Templating**: Familiarity with the double-curly brace `{{ variable }}` syntax. Key Libraries & Tools - Statamic: A flat-file first CMS built on Laravel. - **Antlers**: The built-in templating engine for Statamic, optimized for CMS data. - **Alpine.js**: For lightweight front-end interactivity. - **Tailwind CSS**: The preferred utility-first CSS framework for Statamic sites. - **Vite**: The build tool used for asset compilation. - **PHPStorm**: The IDE used for the code demonstrations. Code Walkthrough: Composable Components and Page Builders 1. Creating Reusable Metadata with Fieldsets Instead of defining SEO fields for every collection, we use Fieldsets to create a "single source of truth." ```yaml metadata.yaml fieldset configuration title: Metadata fields: - handle: meta_title field: type: text display: Meta Title - handle: meta_description field: type: textarea display: Meta Description - handle: og_image field: type: assets max_files: 1 display: Open Graph Image ``` By linking this fieldset in your **Blueprints**, any change to the metadata structure (like adding a canonical URL field) automatically propagates to both your "Pages" and "Movies" collections. 2. The Button Component with Slots To ensure buttons look consistent across the site while remaining flexible, we use partials with slots. ```antlers {{# views/partials/components/button.antlers.html #}} <a href="{{ href ?? '#' }}" class="px-4 py-2 bg-amber-500 rounded text-white hover:bg-amber-600 transition"> {{ slot }} {{ if icon }} <span class="ml-2">{{ partial:icons/{{ icon }} }}</span> {{ /if }} </a> ``` You can then call this button from any template, passing specific markup into the default slot: ```antlers {{ partial:components/button href="/tickets" }} Buy Tickets Now {{ slot:icon }}ticket{{ /slot:icon }} {{ /partial:components/button }} ``` 3. Implementing the Dynamic Page Builder A maintainable Page Builder avoids huge `if/else` chains in your main layout. Instead, use the `type` variable to dynamically load partials. ```antlers {{# In your layout file #}} <div class="page-builder"> {{ page_builder }} {{ partial src="page_builder/{type}" }} {{ /page_builder }} </div> ``` This pattern looks for files in `views/partials/page_builder/`. If the user adds a "Text" set, Statamic loads `text.antlers.html`. If they add a "Random Movies" set, it loads `random_movies.antlers.html`. This keeps each block's logic isolated and clean. Syntax Notes: Antlers Best Practices - **The Colon Prefix (`:`)**: When passing a variable into a partial, use `{{ partial:name :variable="actual_var" }}`. The colon tells Antlers to treat the string as a variable rather than a literal string. - **Local Variables**: Use a leading underscore (e.g., `_my_var`) for variables that are only relevant within a specific partial. This distinguishes them from global entry data. - **Dry Templates**: Use `{{ yield }}` and `{{ section }}` just like you would in Blade to inject scripts or styles into specific parts of your main layout from a nested template. Practical Examples: The "Salt + G" Stack Modern Statamic development often follows the **SALT+G** acronym: Statamic, Alpine.js, Laravel, Tailwind CSS, plus **Git**. Because Statamic is flat-file, your content exists as YAML and Markdown files. By using the Git Integration, content changes made by a client on production are automatically committed and pushed back to your repository. This allows developers to pull down the production content locally without ever touching a database dump. Reducing the Cost of Action in Development Teams While code quality is vital, Max Brokman argues that the most expensive part of software development isn't the CPU cycles—it's the **Cost of Action**. This is the sum of fear, uncertainty, and frustration that prevents a developer from making progress. Eliminating Decision Fatigue Every choice—from which queue driver to use to where to place a utility class—has a cost. 1. **Don't Fight the Framework**: If you are using Laravel, do things the "Laravel Way." Avoid the temptation to bolt on micro-framework patterns that require ten different documentation sites to understand. 2. **Avoid Resume-Driven Development**: Implementing Kafka for a small blog because it looks good on a resume adds massive maintenance debt. Use the simplest tool that solves the problem "right now." Optimizing the "Joiner" Experience A team's health is often measured by how quickly a new developer can run `git clone` and see the application in their browser. - **Seeders over Dumps**: Never rely on production database dumps for local dev. Maintain robust seeders and factories. - **The "Nuke" Command**: Create a script that deletes all Docker volumes and rebuilds the environment from scratch. If this script fails, your environment is too fragile. - **Document the "Arcane"**: If a specific environment variable is required for a third-party API, it must be in the `.env.example`. Tips & Gotchas - **Premature Abstraction**: Don't build a component for a button if you only have one button on the entire site. Wait until you see the pattern repeat three times. - **The Scaling Myth**: Many developers over-architect for 100 million users when they currently have zero. Use the `sync` or `database` queue driver until you actually hit a performance ceiling. - **Reviewer Fatigue**: In code reviews, automate the nitpicks. Use tools like Laravel Pint to handle formatting so humans can focus on the architectural logic. - **Read the Docs**: Statamic has world-class documentation. Most "custom" solutions developers build are actually already handled by a built-in tag or fieldtype.