Ttall Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require pktharindu/ttall
   php artisan ttall:install
   

   • Choose between basic (no auth) or auth (with Laravel Breeze/Inertia-like auth scaffolding) during installation.

2. First Use Case

   • Run the dev server:

     npm run dev
     

   • Visit http://localhost:8000 to see the TTALL stack (Tailwind + Turbolinks + Alpine.js) in action.
   • For Livewire integration, create a component:

     php artisan make:livewire Welcome
     

   • Edit resources/views/welcome.blade.php to include:

     @livewire('welcome')
     

3. Key Files to Review

   • webpack.mix.js (Tailwind + PostCSS config)
   • tailwind.config.js (Customize breakpoints, colors, etc.)
   • resources/js/app.js (Turbolinks + Alpine.js setup)
   • app/Http/Livewire/ (Livewire components)

Implementation Patterns

Core Workflows

1. Frontend Development

   • Tailwind CSS: Use utility classes directly in Blade:

     <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
         Click Me
     </button>
     

   • Turbolinks: Enable seamless navigation. Use data-turbo-permanent for persistent elements:

     <div data-turbo-permanent>
         <nav>...</nav>
     </div>
     

   • Alpine.js: Add interactivity without Livewire:

     <div x-data="{ open: false }">
         <button @click="open = !open">Toggle</button>
         <div x-show="open">Content</div>
     </div>
     

2. Livewire Integration

   • Component Communication: Use Livewire’s built-in features:

     // In Livewire component
     public $count = 0;
     public function increment() {
         $this->count++;
     }
     

     <!-- In Blade -->
     <button wire:click="increment">Count: {{ $count }}</button>
     

   • Authentication: Leverage Laravel UI concerns (e.g., throttling) via Livewire actions:

     @auth
         <livewire:auth.logout-button />
     @endauth
     

3. Package Extensions

   • Debugging: Use Laravel Debugbar (included) for SQL/performance insights.
   • Linting/Format: Run ESLint + Prettier via:

     npm run lint
     npm run format
     

   • PHP Quality: Use Larastan (PHPStan) and PHP CS Fixer:

     composer test
     

4. Asset Pipeline

   • Customization: Modify webpack.mix.js to add/remove dependencies:

     mix.js('resources/js/app.js', 'public/js')
          .postCss('resources/css/app.css', 'public/css', [
              require('tailwindcss'),
          ]);
     

   • Hot Reload: Use Vite (if migrated) or Laravel Mix:

     npm run dev -- --hot
     

Gotchas and Tips

Pitfalls

1. Turbolinks Caching

   • Issue: Turbolinks may cache stale views. Use data-turbo-action="replace" to force refresh:

     <a href="/page" data-turbo-action="replace">Force Refresh</a>
     

   • Debug: Check browser console for Turbolinks errors (e.g., Turbolinks is not defined).

2. Livewire + Turbolinks Conflicts

   • Fix: Ensure Livewire’s wire:init events are not duplicated. Use wire:ignore for non-Livewire elements:

     <div wire:ignore>
         <select x-model="selectedOption">
             <!-- Alpine.js select -->
         </select>
     </div>
     

3. Tailwind JIT (Just-in-Time) Mode

   • Warning: JIT mode (tailwind.config.js) may increase build time. Disable if using small projects:

     module.exports = {
         purge: [
             './resources/**/*.blade.php',
             './resources/**/*.js',
         ],
         // Disable JIT for production
         jit: process.env.NODE_ENV !== 'production',
     };
     

4. Alpine.js + Livewire State

   • Tip: Avoid mixing Alpine.js and Livewire state management. Use one or the other per component.

5. Archived Package Risks

   • Mitigation: Fork the repo or pin versions in composer.json:

     "require": {
         "pktharindu/ttall": "1.0.0"
     }
     

Debugging Tips

1. Tailwind Classes

   • Use tailwindcss-intellisense in VSCode for autocomplete.
   • Check node_modules/tailwindcss/lib/util/flattenColorPalette.js for generated colors.

2. Livewire Events

   • Listen for Livewire events in Alpine.js:

     <div x-data @livewire:init="console.log('Livewire ready')">
         <!-- Content -->
     </div>
     

3. Turbolinks Navigation

   • Override Turbolinks behavior with custom JS:

     document.addEventListener('turbolinks:load', () => {
         console.log('Page loaded via Turbolinks');
     });
     

4. Composer Hooks

   • Disable Git hooks temporarily:

     composer hooks:disable
     

Extension Points

1. Custom Tailwind Config

   • Extend tailwind.config.js:

     module.exports = {
         theme: {
             extend: {
                 colors: {
                     'brand': '#3b82f6',
                 },
             },
         },
     };
     

2. Livewire Component Templates

   • Create a custom Livewire stub:

     php artisan make:livewire --stub=custom-stub Welcome
     

   • Update stubs/livewire.stub in the package.

3. Alpine.js Plugins

   • Register custom plugins in resources/js/app.js:

     import Alpine from 'alpinejs';
     import focus from '@alpinejs/focus';
     
     Alpine.plugin(focus);
     

4. Turbolinks Visitor

   • Customize Turbolinks visitor for analytics:

     document.addEventListener('turbolinks:visit', (event) => {
         // Track page visits
     });
     

5. IDE Helpers

   • Generate IDE helpers for Laravel models:

     php artisan ide-helper:generate