laravel-shift/blueprint: generating Laravel components from a YAML draft

What Blueprint is for, and who it is not for

Blueprint is a code generation tool for Laravel developers, published by laravel-shift under the MIT licence. The README describes it as an open-source tool for rapidly generating multiple Laravel components from a single, human readable definition. The problem it addresses is the repetition that comes with starting a feature: a model, a migration, a factory, a controller, routes, a form request, a job, an event, a Blade template and two tests, all of which have to agree with each other about column names, validation rules and constructor properties. Blueprint derives that agreement from one file rather than from your memory.

The audience is narrow on purpose. The requirements section states Blueprint needs a Laravel application running a supported version of Laravel, currently Laravel 11 or higher. If you are on an older release, the support policy is explicit: starting with version 2, Blueprint only generates code for supported versions of Laravel, and the README suggests constraining Blueprint to an older version or upgrading the application. That is a real boundary, not a footnote. A team on Laravel 10 cannot simply install the current release and expect it to work against the framework version it targets.

It is also not a runtime library. Nothing generated by Blueprint ships as a dependency of your application. It is a dev dependency that writes files into your project, and the files it writes are ordinary Laravel classes you then own.

The draft file is the whole mechanism

Blueprint has no database introspection step and no interactive wizard described in the README. The input is a draft file containing a definition of the components to generate, written in YAML. The README's example is twenty lines that declare one model and one controller:

models:
  Post:
    title: string:400
    content: longtext
    published_at: nullable timestamp
    author_id: id:user

controllers:
  Post:
    index:
      query: all
      render: post.index with:posts

From that, the README lists the generated output: a model class for Post with fillable, casts and dates properties plus relationship methods; a migration creating the posts table; a factory that sets columns with fake data; a PostController with index and store actions; routes for those actions; a StorePostRequest validating title and content based on the model definition; a ReviewPost mailable, a SyncMedia job and a NewPost event, each with a post property set through the constructor; a post/index.blade.php template; an HTTP test for the controller; and a unit test for the form request.

The controller block is where the design gets interesting. Statements like validate, save, send, dispatch, fire, flash and redirect are not free-form PHP. They are a vocabulary the tool parses, and the Blueprint docs page for controller statements is where that vocabulary is defined. This is the trade-off at the centre of the tool: you give up writing PHP directly in exchange for a compact declarative form, and you accept that the set of things you can express is the set of statements the grammar knows. Anything outside it has to be written by hand after generation, and hand-written code in a generated file is the classic way these workflows decay.

The repository layout reflects that split. There is a src/ directory for the generator, a stubs/ directory holding the templates that generated files are rendered from, a config/ directory, and a schema.json at the top level, which is consistent with a tool that validates its own input format. The README does not document what schema.json is used for at runtime, so treat that as an inference from the file name rather than a documented feature.

Installing Blueprint and generating the blog example

Blueprint installs as a Composer dev dependency. The README gives this command:

composer require -W --dev laravel-shift/blueprint

The -W flag allows Composer to update dependencies in composer.lock as needed, and --dev keeps it out of production installs. The README states Blueprint will automatically register itself using package discovery, so there is no service provider to add to config/app.php.

If you intend to run the tests Blueprint generates, the README asks you to install a second package:

composer require --dev jasonmccreary/laravel-test-assertions

Generation runs through an Artisan command:

php artisan blueprint:build

That command reads the draft file and writes the components. The README's example assumes features within a default Laravel application such as the User model and app.blade.php layout, and warns that otherwise the generated tests may have failures. That warning matters more than it looks: the author_id: id:user line in the draft implies a relationship to a User model, and the controller's render statement implies a Blade layout exists. On a stripped-down application you will get files that reference things that are not there.

A sensible first run is the README's twenty-line draft in a throwaway Laravel 11 application, followed by reading every generated file before committing anything. The README does not document a dry-run flag, so plan on inspecting the diff in version control rather than previewing output.

Where Blueprint stops being the right tool

The most concrete limitation is the Laravel version floor. The support policy states that starting with version 2, Blueprint only generates code for supported versions of Laravel, currently Laravel 11 or higher. If your application is on an older release, the current major version is not aimed at you, and the README's own suggestion is to constrain Blueprint to an older version or upgrade the application. Constraining means you stop receiving new features and new Laravel code generation, which is a maintenance decision, not a workaround.

The second limitation is regeneration. The README does not document rollback, and it does not describe how Blueprint behaves when a generated file has been edited by hand and the draft is run again. That silence is the thing to test in a scratch repository before you build a workflow around it. If you edit PostController after generating it, you need to know from experiment, not from the README, whether the next blueprint:build overwrites your changes.

The third is the grammar ceiling. Semantic versioning here is applied to the grammar: the README states that any changes to the grammar will increase its major version number, while minor version increases contain new features, including generating code for future versions of Laravel. So a major bump in Blueprint is a signal that your draft files may need editing, not just that the package changed. If your team cannot absorb that kind of upgrade, Blueprint is the wrong layer to depend on.

Finally, the generated tests are a starting point, not coverage. The README lists an HTTP test and a unit test, and notes they may fail outside a default application skeleton. Treating a passing generated test suite as evidence that a feature works would be a misreading of what the tool produces.

Blueprint against writing the code yourself or using a starter kit

The obvious alternative is not another generator. It is Laravel's own starter kits and artisan make:* commands, or simply writing the classes. The difference in approach is where the shared definition lives. With make:model, make:controller and make:migration, each command knows about one artifact and nothing about the others, so the consistency between a migration column named published_at and a model cast for the same column is maintained by you. Blueprint inverts that: the draft is the definition, and the individual artifacts are derived from it. That is the whole value proposition, and it is also why the draft file becomes something your team has to review and version.

A starter kit takes a third position. It gives you a working application skeleton with authentication and a layout already in place, which is exactly the context the README's example assumes exists. Blueprint does not provide that skeleton; it generates feature-level components into whatever application you point it at. If what you need is a project starting point, a starter kit addresses that and Blueprint does not. If what you need is the fifth CRUD feature in an existing application, Blueprint addresses that and a starter kit does not.

The honest framing is that Blueprint competes with your editor's snippets and your own discipline. It wins when the definition of a feature is genuinely repetitive and you are willing to keep the draft file in sync with reality. It loses when features are unusual enough that most generated files get rewritten, because then you have paid the cost of learning the grammar and received little back.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-08-11. Recent releases are v2.13.0 on 2025-11-20, v2.12.0 on 2025-04-16 and v2.11.1 on 2025-02-12. Those dates describe the release cadence; they say nothing about whether a given draft file will survive an upgrade.

The upgrade cost is concentrated in the grammar, and the README is explicit about how that is versioned: changes to the grammar increase the major version number. In practice that means reading UPGRADE.md, which sits at the top level of the repository, before moving between major versions, and checking whether any statement in your draft files changed meaning. Minor releases are described as containing new features, including generation for future Laravel versions, so a minor bump is the safer kind of upgrade but still one that changes what files Blueprint emits.

Because Blueprint is a dev dependency, it does not ship to production, and the MIT licence covers the package itself. The generated code is your code; the README does not state a separate licence for generated output, and nothing in the repository documentation addresses what obligations, if any, attach to files produced by the stubs in stubs/. If that distinction matters to your organisation, raise it with whoever handles licensing rather than assuming either way. This is a description of what the repository says, not legal advice.

The other ongoing cost is the second dev dependency. Running generated tests requires jasonmccreary/laravel-test-assertions, so your test environment carries both packages, and both need to stay compatible with the Laravel version you are on.

Editorial conclusion

Adopt Blueprint if you are starting Laravel 11 or higher projects and want a draft file to be the source of truth for models, controllers, routes and tests. Skip it if you maintain a pre-Laravel 11 application, since the support policy states version 2 only generates code for supported Laravel versions, or if you want generated code you will never regenerate. Before committing, install it in a scratch application, run php artisan blueprint:build against the README's twenty-line blog draft, and read every generated file to see how much of it you would actually keep.

Frequently asked questions

Official sources

1. Issues
2. laravel-shift/blueprint on GitHub
3. License: MIT
4. README
5. Releases