Indigo Layout Laravel Package

Getting Started

1. Install: composer require awes-io/indigo-layout. The service provider is auto-discovered on Laravel 5.5+, so no manual registration is needed.
2. Publish what you need: This is a UI package, so the first move is almost always asset/view publishing rather than config:

   php artisan vendor:publish --provider="AwesIO\IndigoLayout\IndigoLayoutServiceProvider"
   

   Publish the public assets (CSS/JS) and, if you intend to restyle, the views/SCSS so they land in resources/.
3. Look here first:
   • The package README on GitHub for the canonical markup snippets.
   • vendor/awes-io/indigo-layout/resources/views/ — this is the source of truth for component names, slots, and expected props. Read the Blade, not the docs, when they disagree.
   • config/indigo-layout.php (if published) for toggles like asset injection or component registration.
4. First use case: Drop the package's layout into a fresh Laravel app as an admin shell — a blade layout with a header/sidebar/content slot — then add a form and a button from the component set. That single page validates that assets load, the view namespace resolves, and your build pipeline plays nicely.

Implementation Patterns

• Layout wrapping: Treat the package layout as your base app.blade.php equivalent. Extend it (@extends('indigo-layout::...')) or @include it inside your own layout, then fill named sections/slots for content, scripts, and styles. Keeping your own thin layout on top of it makes later upgrades far cheaper than editing the vendor view directly.
• Blade components: Use the package components as building blocks (buttons, form fields, alerts, cards) and pass data through attributes/slots. For repeated groups (e.g. a form row), wrap them in your own Blade component or partial rather than copy-pasting markup — that's where the package earns its keep day-to-day.
• Asset pipeline: Run the package's CSS/JS through your normal build (Laravel Mix/Vite) by importing the published stylesheet/entry, not by hard-coding <link> tags in the layout. This keeps cache-busting and source maps working.
• Theming via variables: Restyle by overriding SCSS variables/CSS custom properties before importing the package stylesheet. Recompile through your bundler; avoid appending override CSS in a <style> block, which leads to specificity arms races.
• Ecosystem integration: If you're using the other AWES packages (form-builder, table-builder), let indigo-layout own the visual layer and let those packages own the data/behavior. Install them in the same order as the AWES starter so component registration and asset ordering match expectations.
• Feature work: Build a page by composing the package layout + components + a small amount of page-specific SCSS/JS. Keep page-specific styles scoped to a page class to avoid leaking into shared components.

Gotchas and Tips

• Publishing is a one-way door for views: Once you publish and edit views, package upgrades no longer reach them. Publish only what you must customize, and diff vendor/ on upgrade to see what you missed.
• Asset cache: After upgrades, run vendor:publish --force for assets (careful with --force on views) and clear compiled views (php artisan view:clear) and your asset cache. Stale CSS is the #1 "the component looks broken" cause.
• Vue/frontend coupling: The AWES stack leans on Vue (often Vue 2-era tooling). Check the package's composer.json/package.json for the Vue version and peer deps before mixing it into a Vite/Vue 3 app — mismatched versions manifest as silent component failures.
• CSS framework collisions: If your app already ships Tailwind/Bootstrap/UIkit, expect class-name and reset conflicts. Load the package styles in a predictable order (base → package → your overrides) and prefer variable overrides over selector wars.
• Namespace debugging: View resolution uses the indigo-layout:: namespace. If a component renders blank, confirm the namespace is registered (php artisan view:clear then check view:cache output) and that your published override isn't shadowing it with a typo'd path.
• Low bus factor: 44 stars, zero dependents, and a single-vendor origin. Pin the version in composer.json ("awes-io/indigo-layout": "x.y.*"), vendor the published assets in git, and have a plan to fork if the upstream goes quiet. Don't build load-bearing UI on it without freezing a known-good version.
• Extension points that actually work: config toggles, published views, SCSS variable overrides, and slots. Reach for those before monkey-patching vendor files; if the package doesn't expose a slot/attribute you need, wrap the component in your own rather than editing it in vendor/.