Blueprint Nova Addon Laravel Package

Getting Started

• Install and pin the pair together. This release matters only in combination with the underlying Blueprint package — add blueprint:^2.0 (or whatever the package's composer.json require block now states) at the same time. Installing this package without the matching Blueprint major is the most common failure mode.

• Read the package's composer.json first, not the README. A "support for blueprint v2" release almost always carries a raised floor on PHP/Laravel, and you want to know that before you start bumping.

• Inspect the service provider and config file. Publish the config (php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" or the tag listed in the README) and confirm which generators/stubs are registered by default. That registration list is the package's actual public surface.

• First use case: point it at a single-model draft and run a dry build:

  php artisan blueprint:build --pretend drafts/example.yaml
  

  Diff the output against what a model/migration generated by Blueprint v2 without this package looks like. The delta is the value the package adds — that's the thing worth understanding before you scale it up to a full schema.

Implementation Patterns

• Draft-as-source-of-truth. Keep drafts/*.yaml in version control and treat generated migrations/models as build artefacts for anything that's regenerated often. With v2 support in place, a blueprint:build run should be reproducible on a clean checkout — assert that in CI rather than trusting it.
• Layer custom generators for house conventions. The typical day-to-day win is encoding your team's defaults (ULIDs, soft deletes on, a standard belongsTo FK naming, a base model stub) once, then never hand-editing the output. Register them explicitly in the config file rather than relying on auto-discovery, so ordering is deterministic.
• Smoke-test the generated code, not the generator. A cheap Pest/PHPUnit test that runs a build into a temp directory and asserts the files parse (php -l) catches stub regressions far earlier than an integration test does.
• Use --pretend in CI on PRs that touch drafts/ or the package's config. It produces a reviewable diff of what the next build would change without dirtying the working tree.
• Version the stubs you override. If you publish and edit stubs, keep them in the repo under stubs/ and reference them by path. Published stubs sitting only in a developer's local tree are the classic "works on my machine" build.

Gotchas and Tips

• v2 is an API break for generator authors, not just a version bump. If you previously wrote a custom generator against the v1 contract, expect the base class signature, the model/tree node accessors, and possibly the stub placeholders to have moved. Re-read the upstream v2 upgrade notes and diff your generator against a freshly published stub before assuming it still works. The package supporting v2 does not mean your subclass does.
• Republishing does not overwrite. vendor:publish --force is required to refresh stubs, and it will happily clobber your edits. Diff first; --force is a footgun on a shared codebase.
• Clear caches after the upgrade. php artisan config:clear and composer dump-autoload — a stale cached config pointing at old generator class names produces confusing "class not found" errors that look like a broken install.
• Debugging a bad build: run with --pretend, then narrow to a single model by trimming the draft. If the output is empty rather than wrong, the parser didn't pick up the model — check YAML indentation and that the draft sits where the package expects it, not the generator.
• Extension points worth knowing: custom generator registration in config, published stub overrides, and any macro/hook surface the package exposes on the Blueprint facade. Prefer these over forking the package — a fork makes the next Blueprint major a manual merge.
• Pin both packages together in CI and in composer.lock. Because support is coupled, a composer update that floats Blueprint but not this package (or vice versa) is the failure you'll spend the most time diagnosing and the least time preventing.