Laravel Tiptap Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require georgeboot/laravel-tiptap
   yarn add laravel-tiptap
   

   Add to app.js:

   import Alpine from 'alpinejs'
   import LaravelTiptap from 'laravel-tiptap'
   Alpine.data('tiptapEditor', LaravelTiptap)
   Alpine.start()
   

2. First Usage Include the component in a Blade view:

   <x-tiptap-editor />
   

   This renders a basic Tiptap editor with default configurations.

3. Key Files to Review

   • resources/views/vendor/laravel-tiptap/ (Blade components)
   • node_modules/laravel-tiptap/dist/ (JS/CSS assets)
   • config/tiptap.php (published via php artisan vendor:publish --provider="GeorgeBoot\LaravelTiptap\LaravelTiptapServiceProvider")

Implementation Patterns

Core Workflows

1. Basic Editor Integration Use <x-tiptap-editor /> for a pre-configured editor with default extensions (bold, italic, lists, etc.). Pass a model prop to bind to a Laravel model:

   <x-tiptap-editor :model="$post->content" />
   

2. Customizing Extensions Override default extensions via config (config/tiptap.php):

   'extensions' => [
       'StarterKit',
       'Underline',
       'CodeBlock', // Add custom extensions
   ],
   

   Or dynamically via Alpine:

   Alpine.data('tiptapEditor', (defaultConfig) => ({
       ...defaultConfig,
       extensions: [
           ...defaultConfig.extensions,
           'CodeBlock',
       ],
   }))
   

3. Image Uploads Enable with <x-tiptap-editor enable-image-upload />. Ensure S3 disk is configured (see README) and add a route for uploads:

   Route::post('/tiptap-upload', [TiptapController::class, 'upload'])->name('tiptap.upload');
   

4. Form Submission Bind the editor to a form field (e.g., textarea hidden via CSS):

   <form method="POST">
       <x-tiptap-editor name="content" />
       <textarea name="content" style="display: none;"></textarea>
       <button type="submit">Save</button>
   </form>
   

5. Dynamic Initialization Use Alpine to conditionally load the editor:

   @if(auth()->check())
       <x-tiptap-editor :model="$user->bio" />
   @endif
   

Integration Tips

• Laravel Models: Use HasTiptapContent trait (if provided) or manually cast attributes:

  protected $casts = [
      'content' => 'tiptap',
  ];
  

• Validation: Validate Tiptap content in Laravel:

  $request->validate([
      'content' => 'required|string',
  ]);
  

• Livewire/Inertia: Pass the editor’s state via props or store it in a hidden input before submission.
• Tailwind CSS: Extend your tailwind.config.js to purge the package’s views (as shown in README).

Gotchas and Tips

Pitfalls

1. Missing Alpine Initialization Forgetting to add Alpine.data('tiptapEditor', LaravelTiptap) will break the editor. Fix: Ensure app.js includes the line after Alpine is imported.

2. S3 Uploads Without CloudFront If using S3 directly (without CloudFront), URLs may return 403 Forbidden due to S3’s default permissions. Fix: Configure CORS for your bucket or use CloudFront.

3. Tailwind Purge Issues Forgetting to add the package’s views to purge in tailwind.config.js may cause styles to disappear. Fix: Include:

   './vendor/georgeboot/laravel-tiptap/resources/views/**/*.blade.php'
   

4. CSRF Token for Uploads Image uploads require CSRF protection. Ensure your upload route includes @csrf in Blade or the token in the request headers. Fix: Add @csrf to your Blade form or include _token in AJAX requests.

5. Editor State Not Persisting If the editor’s content isn’t saved, check:

   • The hidden textarea has the correct name attribute.
   • The form submission includes the textarea (not just the editor’s DOM).

Debugging

1. Console Errors Check browser console for errors like Uncaught ReferenceError: Tiptap is not defined. This usually means the JS bundle isn’t loaded. Fix: Verify yarn build was run and assets are published (php artisan tiptap:assets).

2. Upload Failures If images fail to upload, check:

   • S3 disk configuration in .env.
   • Storage permissions (chmod -R 775 storage).
   • Network tab for failed requests (e.g., CORS or auth issues).

3. Extension Conflicts If the editor behaves unexpectedly, disable custom extensions one by one to isolate the issue.

Tips

1. Custom Toolbar Override the toolbar via config:

   'toolbar' => [
       'bold', 'italic', 'bulletList', 'orderedList', 'codeBlock',
   ],
   

   Or dynamically in Alpine:

   toolbar: [
       'bold', 'italic', 'image', // Customize toolbar
   ],
   

2. Dark Mode Support Add a dark prop to the component:

   <x-tiptap-editor dark />
   

   (If not supported, extend the package’s CSS.)

3. Local Development Use yarn dev for hot-reloading during development:

   // vite.config.js
   export default defineConfig({
       server: {
           hmr: {
               host: 'localhost',
           },
       },
   });
   

4. Extending the Package Publish the config and views for customization:

   php artisan vendor:publish --provider="GeorgeBoot\LaravelTiptap\LaravelTiptapServiceProvider" --tag="config"
   php artisan vendor:publish --provider="GeorgeBoot\LaravelTiptap\LaravelTiptapServiceProvider" --tag="views"
   

5. Performance Lazy-load the editor if it’s not always needed:

   @if($shouldShowEditor)
       <x-tiptap-editor />
   @endif