Statamic Peak Commands Laravel Package

Getting Started

This package adds a make:partial artisan command that scaffolds reusable Blade partials instead of hand-creating files. As of v11.1.0, it can also emit a companion CSS file for the new partial and wire the @import into your stylesheet, so a partial ships with its own styling in one step.

Minimal steps:

1. Install the package and publish its config/stubs (php artisan vendor:publish --tag=... for the package's config and stub groups — check php artisan vendor:publish output, then read config/partials.php first; that is where the output path, stub selection, and the CSS file location/import target are defined).
2. Run php artisan make:partial card to confirm the baseline behaviour and where files land.
3. Run it again with the CSS option enabled (the new v11.1.0 flag/prompt) and diff the generated resources/css/app.css (or whatever your configured entrypoint is) to confirm the import is appended where you expect.
4. Include the partial in a view and check styling works through Vite.

First use case: take an existing chunk of markup repeated across two or three Blade views (a card, a pricing tier, a meta row), regenerate it as a partial with its own stylesheet, and swap the copies for @include/<x-...> calls. That gives you the value of the package in a single afternoon and validates your config before the team adopts it.

Start by reading, in order: the config file, the published stubs, and php artisan list output for the make:partial signature and options.

Implementation Patterns

Scaffold-with-styles as the default for new UI. Once v11.1.0's CSS option is on, treat "partial + CSS file" as the default unit of work: one partial, one stylesheet, one import line. Keeping style ownership co-located with markup is the whole point of the feature and it makes deletion trivial later.

Refactor-then-extract loop. Copy the existing markup into the partial, then delete the original blocks one at a time, running the page between edits. Extracting several blocks at once makes it hard to attribute a visual regression to a specific partial.

Directory and naming conventions. Decide early whether partials live flat or nested, and mirror that in CSS file naming (card.blade.php → card.css). Enforce the convention with the config path/stub rather than code review comments — the generator should make the right thing the easy thing.

Passing data deliberately. Use explicit @include('partials.card', ['item' => $item]) for simple partials and slots/anonymous components where you need default content or attributes. Avoid @include calls that rely on implicitly inherited parent variables; they make partials un-reusable and untestable.

Vite/Tailwind integration. If your CSS entrypoint is Tailwind-driven, the generated import must be processed by the same pipeline — verify hot reload picks up the new file without a manual restart, and add the partials directory to Tailwind's content globs if it sits outside the default resources/views tree.

Batch generation during bootstrap. When introducing the package to an existing codebase, script the generation of a handful of known partials in CI or a one-off command so the stub output is consistent across the team, rather than each dev hand-tweaking their first few files.

Guard the imports. If your stylesheet is shared, keep generated imports grouped (e.g. all appended in one block) so review diffs stay readable and ordering conflicts between two partials' styles are visible.

Gotchas and Tips

• The CSS feature only applies to newly generated partials. Running make:partial against something that already exists will not backfill a stylesheet — you either hand-create the CSS file and add the import, or delete/regenerate. Plan migrations accordingly.
• Import duplication. Regenerating or re-running the command can append a second @import for the same file if the command does not dedupe. Check the stylesheet after repeated runs and clean up before committing.
• The import target is config-driven. If your project uses a non-default entrypoint (resources/css/app.css vs. a Sass file, or a bundled app.ts import chain), update the config before generating anything, otherwise imports land in a file that Vite never processes and styles silently do nothing.
• Silent no-op styling. A generated CSS file with no import, or an import in an unprocessed file, fails quietly. When a partial "has no styles", check the import line and the Vite entrypoint before debugging CSS itself.
• Build tooling restarts. New files added to the Tailwind/Vite graph sometimes need a dev-server restart or a content glob that is not too narrow (avoid depth-limited globs that miss nested partial directories).
• Caches. After changing config or stubs, run php artisan config:clear and php artisan view:clear; stale compiled views hide partial path changes.
• Dynamic class names in partials (concatenated Tailwind classes) will not be picked up by the scanner — safelist them or restructure the partial to take a variant prop instead.
• Stub drift. Publish the stubs if the team needs a house style (header comment, strict types, specific indentation); an unpinned stub is a small breaking change whenever the package updates it. Re-check stubs on minor releases like this one.
• Diff noise. The auto-append to a shared stylesheet touches a file many people edit. Land the config and the first few generations in a dedicated PR to avoid import-order conflicts.
• Extension points worth knowing: the config file (paths, stub selection, CSS import target), the published stubs (for markup and CSS boilerplate), and the command signature itself — wrap it in a project-specific artisan command if you need extra steps like registering the partial in a manifest or generating a test.