bladewell / starter-kit

v2026.10.3 2026-10-06 08:42 UTC

Requires

• php: ^8.3
• laravel/framework: ^13.17
• laravel/tinker: ^3.0

Requires (Dev)

• bladewell/bladewell: ^0.3.0
• fakerphp/faker: ^1.23
• laravel/boost: ^2.10
• laravel/pail: ^1.2.5
• laravel/pao: ^1.0.6
• laravel/pint: ^1.27
• mockery/mockery: ^1.6
• nunomaduro/collision: ^8.6
• phpunit/phpunit: ^12.5.12

MIT

• Krishnaprasad R

• Authentication
• laravel
• blade
• starter-kit
• tailwind
• bladewell

Published on Packagist.org on 2026-10-06 08:45 UTC

README

A Laravel starter kit with sign in, registration, password reset, email verification and account settings, built from Bladewell widgets.

Plain Blade and a small vanilla JS module per widget: no React, Vue, Inertia or Alpine. Works under a strict Content Security Policy.

Start a new app

composer create-project bladewell/starter-kit my-app
cd my-app
npm install && npm run build
composer run dev

With the Laravel installer, laravel new my-app --using=bladewell/starter-kit does the same first step. (No laravel command? composer global require laravel/installer installs it.)

It uses SQLite by default. For MySQL, set the DB_* values in .env, then run php artisan migrate.

To try it with data, run php artisan db:seed: it creates [e-mail] (password password) with a few pages of sign-in history for the dashboard table. The home page links to every page; the ones behind sign in ask for it first, then go straight there.

What's included

Page	Route	Widgets
Sign in	/login	text-input, password, checkbox, button, alert
Create account	/register	text-input, password (with its rule checklist), button
Forgot / reset password	/forgot-password, /reset-password/{token}	text-input, password, button, alert
Verify email	/verify-email	button, alert
Confirm password	/confirm-password	password, button
Dashboard: your sign-in history	/dashboard	table (sortable, paginated, cards on phones), alert, dropdown account menu, accordion menu sidebar on large screens
Settings	/settings/profile	text-input, password, button, breadcrumbs, modal (other devices, delete account), toast

New accounts verify their email before reaching the dashboard; in development the link is written to storage/logs/laravel.log (MAIL_MAILER=log). To skip verification, remove implements MustVerifyEmail from app/Models/User.php.

Security

Safe by default, and every choice is in one file, config/security.php, with a comment on what changing it costs. Sign-in is rate limited, passwords need 12+ characters (and are checked against known breaches in production), changing your email asks for your password, a password change signs out your other sessions, and every page sends a strict Content Security Policy.

SECURITY.md has the full list, a checklist for going live, and what to change when your app adds Stripe, analytics, embedding or Livewire.

Where things live

routes/auth.php                         sign in, registration, password reset, verification
routes/web.php                          dashboard and settings
app/Http/Controllers/Auth/              the auth controllers
app/Http/Controllers/Settings/          profile, password, other devices
app/Http/Middleware/SecurityHeaders.php the Content Security Policy and other browser security headers
app/Listeners/RecordSignIn.php          keeps the sign-in history
config/security.php                     every security setting, explained
resources/views/components/layouts/     app (sidebar on large screens, header and account menu) and guest (centred card)
resources/views/auth/                   the auth pages
resources/views/components/theme-toggle.blade.php   the Light / Dark / System menu
resources/js/theme.js, theme-boot.js    switching the theme, and applying it before the page is drawn
resources/views/components/widget/      Bladewell widgets: yours to edit
resources/js/widget/, resources/css/widget/
bladewell.lock                         which widget files you've edited; commit it

Widgets

The widgets are copied into your app, so you can change them freely. To add more:

php artisan bladewell:list
php artisan bladewell:add datepicker

Keeping widgets up to date

Your app keeps the widgets exactly as they were when you created it; nothing changes behind your back. New Bladewell releases bring fixes and new widgets, and you take them when you choose:

composer require --dev bladewell/bladewell:^0.3   # move to the new release (the version from its changelog)
php artisan bladewell:add --installed                # update the widget files you haven't edited
php artisan bladewell:diff                           # see what changed in the ones you have
php artisan bladewell:add new-widget                 # add a widget that's new in that release

bladewell:add --installed never overwrites a file you've edited: it reports it, and bladewell:diff shows the difference so you can merge by hand. bladewell.lock is how it tells them apart, so commit it.

While Bladewell is below 1.0, composer update alone stays within the minor version you have: ^0.2.1 gets 0.2.x fixes but never 0.3.0, as Composer treats each 0.x minor release as possibly breaking. That's why the first command names the version. Read the changelog for the widgets you use before moving.

AI agents

The kit is ready for AI coding agents (Claude Code, Codex, Cursor, Copilot and others):

• Laravel Boost gives them this app's Laravel version, database schema, logs, errors and version-matched Laravel docs, through its MCP server (php artisan boost:mcp).
• php artisan bladewell:mcp lets them look up every widget's props and examples, and install widgets.
• CLAUDE.md and AGENTS.md tell them how to work here: the kit's rules (widgets, the Content Security Policy, config/security.php, tests) and a careful working style.

Claude Code finds both MCP servers in .mcp.json by itself. For another agent, run php artisan boost:install and pick it: Boost writes that agent's MCP settings and instructions file; add bladewell (php artisan bladewell:mcp) next to laravel-boost there. CLAUDE.md and AGENTS.md are generated, so write your own rules in .ai/guidelines/, then run php artisan boost:update.

Commit these files: they're the project's instructions, so every agent and every teammate works by the same rules, and changes to them get reviewed like code. Your personal ones stay out of git: CLAUDE.local.md, .claude/settings.local.json, .codex/ and .cursor/ are in .gitignore. Never put API keys in .mcp.json; use environment variables.

Boost is a development dependency: deploy with composer install --no-dev and it isn't on your server.

Tests

php artisan test

Every flow above has a feature test in tests/Feature.

Versions

The kit is versioned by date: 2026.10.0 is the first release of October 2026, and 2026.10.1 a fix to it. You copy a starter kit once rather than upgrade it, so the version says how fresh your copy is. CHANGELOG.md lists what each release changed.

License

MIT. See LICENSE.