Laravel Tiptap Laravel Package

Getting Started

Minimal Setup

1. Installation

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

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="Wabsa\LaravelTiptap\LaravelTiptapServiceProvider"
   

2. Initialize Alpine.js In resources/js/app.js:

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

3. First Usage Add the editor component to a Blade file:

   <x-tiptap-editor />
   

First Use Case: Basic Rich Text Field

• Use <x-tiptap-editor /> in a form to replace a standard <textarea>.
• Bind the editor to a model field via wire:model (Livewire) or x-model (Alpine):

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

Implementation Patterns

Core Workflows

1. Livewire Integration

   • Use wire:model to sync editor content with Livewire properties:

     <x-tiptap-editor wire:model="article.body" />
     

   • Access the HTML content via $this->article->body in Livewire.

2. Alpine.js Standalone

   • Bind to Alpine data:

     <x-tiptap-editor x-model="editorContent" />
     

   • Access via editorContent in your Alpine component.

3. Form Submission

   • The editor outputs sanitized HTML. Ensure your form submission handles HTML input (e.g., fillable fields in models):

     // Model
     protected $fillable = ['content'];
     

Advanced Patterns

1. Custom Extensions

   • Register extensions via the extensions prop:

     <x-tiptap-editor :extensions="['strike', 'codeBlock']" />
     

   • Or pass a custom config object:

     <x-tiptap-editor :config="{
         extensions: [
             Strikethrough.extend(),
             CodeBlock.extend()
         ]
     }" />
     

2. Image Uploads

   • Enable with <x-tiptap-editor enable-image-upload />.
   • Configure the S3 disk (see README) and ensure the uploadImage endpoint is set up (see Gotchas).

3. Toolbar Customization

   • Override the default toolbar via the toolbar prop:

     <x-tiptap-editor :toolbar="[
         ['bold', 'italic'],
         ['bulletList', 'orderedList'],
         ['cleanBlocks']
     ]" />
     

4. Model Binding with Livewire

   • For nested models, bind to a property and update it in Livewire:

     <x-tiptap-editor wire:model="post.sections.0.content" />
     

   • In Livewire:

     public $post = [
         'sections' => [['content' => '']],
     ];
     

Gotchas and Tips

Common Pitfalls

1. Image Uploads Not Working

   • Ensure:
     • The S3 disk is properly configured (config/filesystems.php).
     • The uploadImage endpoint is accessible (the package expects a route at /upload-image).
     • CORS is configured for your S3 bucket if using CloudFront.
   • Debug by checking the network tab for failed upload requests.

2. HTML Sanitization Issues

   • The editor sanitizes output by default. If you need to allow specific tags/attributes, extend the sanitizer:

     // In your Alpine component
     sanitize: (html) => {
         return DOMPurify.sanitize(html, {
             ALLOWED_TAGS: ['b', 'i', 'u', 'img', 'a'],
             ALLOWED_ATTR: ['href', 'src', 'class']
         });
     }
     

3. Tailwind CSS Purge

   • If using Tailwind, add the package’s views to your purge config:

     purge: [
         './resources/**/*.blade.php',
         './vendor/wabsa/laravel-tiptap/resources/views/**/*.blade.php',
     ]
     

4. Livewire Property Updates

   • If the editor content doesn’t update Livewire properties, ensure:
     • The wire:model is correctly bound.
     • There are no JavaScript errors preventing Alpine from updating the model.

Debugging Tips

1. Check Console Logs

   • Add console.log to the Alpine component to verify data binding:

     Alpine.data('tiptapEditor', (props) => ({
         init() {
             console.log('Editor initialized with props:', props);
         },
         // ...
     }));
     

2. Inspect Network Requests

   • For image uploads, verify the request payload and response in the browser’s DevTools (Network tab).

3. Disable Sanitization Temporarily

   • To debug HTML output, disable sanitization in the component:

     <x-tiptap-editor sanitize="false" />
     

Extension Points

1. Custom Endpoints

   • Override the default uploadImage endpoint by passing a custom URL:

     <x-tiptap-editor upload-url="/custom-upload-endpoint" />
     

2. Pre-configured Extensions

   • Extend the package’s default extensions by publishing the config:

     php artisan vendor:publish --tag="laravel-tiptap-config"
     

   • Modify config/tiptap.php to add/remove extensions.

3. Alpine Component Overrides

   • Override the default Alpine component by publishing the views:

     php artisan vendor:publish --tag="laravel-tiptap-views"
     

   • Customize resources/views/vendor/laravel-tiptap/editor.blade.php.