Laravel Mailcoach Monaco Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-mailcoach-monaco
   

   Ensure spatie/laravel-mailcoach is also installed (this package is an editor extension for Mailcoach).

2. Configuration:

   • Publish the config file:

     php artisan vendor:publish --provider="Spatie\MailcoachMonaco\MailcoachMonacoServiceProvider"
     

   • Update config/mailcoach.php to set 'editor' => 'monaco' under the mailcoach key.

3. First Use Case:

   • Navigate to Mailcoach’s email editor in your admin panel. The Monaco editor (a lightweight, powerful code editor) will replace the default editor, offering syntax highlighting, autocompletion, and real-time collaboration features.

Implementation Patterns

Core Workflows

1. Editor Integration:

   • Replace the default Mailcoach editor seamlessly. The package hooks into Mailcoach’s email template system, ensuring Monaco’s editor is loaded only where needed (e.g., mailcoach.emails.edit view).
   • Example Blade Usage:

     @mailcoachEditor
     

     This directive injects the Monaco editor into the template form.

2. Customizing Editor Options:

   • Override Monaco’s default settings via the mailcoach-monaco config:

     'monaco' => [
         'theme' => 'vs-dark', // 'vs', 'vs-dark', or custom themes
         'language' => 'html', // Default language mode
         'options' => [
             'fontSize' => 14,
             'wordWrap' => 'on',
         ],
     ],
     

   • Dynamically pass options via JavaScript:

     window.MailcoachMonacoOptions = {
         theme: 'my-custom-theme',
         minimap: { enabled: false },
     };
     

3. Extending Functionality:

   • Add Language Support: Register custom languages (e.g., for handlebars templates) by extending Monaco’s language definitions:

     monaco.languages.register({ id: 'handlebars' });
     monaco.languages.setMonarchTokensProvider('handlebars', yourTokensProvider);
     

     Load these in a custom JS file included in your Mailcoach assets.

   • Custom Keybindings: Override or extend Monaco’s keybindings via the keybindings config array:

     'keybindings' => [
         'cmd+shift+p' => 'editor.action.quickCommand',
     ],
     

4. Asset Management:

   • The package auto-loads Monaco’s CSS/JS via Laravel Mix. For custom builds:
     • Ensure resources/js/mailcoach-monaco.js exists and is compiled.
     • Override the default asset paths in config:

       'assets' => [
           'js' => 'custom/monaco-editor.js',
           'css' => 'custom/monaco-theme.css',
       ],
       

Gotchas and Tips

Pitfalls

1. Asset Loading Conflicts:

   • Issue: Monaco’s JS/CSS may conflict with other editors or libraries (e.g., TinyMCE, CodeMirror).
   • Fix: Explicitly load Monaco only in Mailcoach contexts. Use Laravel Mix’s only flag:

     // mix.js('resources/js/mailcoach-monaco.js', 'public/js')
         .only(['mailcoach-monaco']);
     

2. Performance Overhead:

   • Issue: Monaco is resource-intensive (~2MB minified). Lazy-load it only when editing emails.
   • Fix: Use dynamic imports or defer loading:

     if (window.location.pathname.includes('/mailcoach/emails')) {
         import(/* webpackMode: "lazy" */ './monaco-editor');
     }
     

3. Configuration Overrides:

   • Issue: Config changes may not reflect immediately due to caching.
   • Fix: Clear Mailcoach’s view cache:

     php artisan view:clear
     php artisan cache:clear
     

4. Language Mode Mismatches:

   • Issue: Monaco defaults to HTML mode, which may not support Mailcoach’s template syntax (e.g., {{ variables }}).
   • Fix: Register a custom language or use HTML with embedded comments:

     monaco.languages.register({ id: 'mailcoach-html' });
     monaco.languages.setLanguageConfiguration('mailcoach-html', {
         comments: { lineComment: '{{#', blockComment: ['{{/*', '*/}}'] },
     });
     

Debugging Tips

1. Editor Not Loading:

   • Check browser console for 404 errors on Monaco’s assets. Verify paths in config/mailcoach-monaco.php.
   • Ensure spatie/laravel-mailcoach is installed and configured.

2. Syntax Highlighting Issues:

   • Test Monaco’s language support in isolation:

     monaco.editor.create(document.getElementById('editor'), {
         value: '<div>{{ name }}</div>',
         language: 'html',
         theme: 'vs-dark',
     });
     

   • Use Monaco’s playground to debug configurations.

3. Custom Themes:

   • If using a custom theme, ensure it’s properly compiled and referenced:

     /* resources/css/monaco-theme.css */
     .monaco-editor .view-lines {
         background: #1e1e1e;
     }
     

Extension Points

1. Custom Editor Commands:

   • Extend Monaco’s command palette to add Mailcoach-specific actions (e.g., "Insert Variable"):

     monaco.editor.registerCommand(monaco.Uri.parse('mailcoach://insert-variable'), () => {
         // Logic to insert {{ variables }}
     });
     

2. Real-Time Collaboration:

   • Integrate with Monaco’s collaborative editing for team workflows. Requires backend support (e.g., WebSockets).

3. Plugin System:

   • Leverage Monaco’s extension API to add:
     • Custom linting for Mailcoach templates.
     • Snippets for common email patterns (e.g., buttons, tables).
   • Example snippet registration:

     monaco.editor.registerSnippet('mailcoach-button', {
         content: '<a href="#" style="display: inline-block; padding: 10px 20px; background: #0066cc; color: white; text-decoration: none;">Button</a>',
         prefix: 'button',
     });