Weave Code
Mjml Sidecar Laravel Package
spatie/mjml-sidecar
Compile MJML email templates to responsive HTML via AWS Lambda using Sidecar. A companion to spatie/mjml-php: deploy the provided MjmlFunction, then call Mjml::new()->sidecar()->toHtml($mjml) to render HTML without local Node/MJML.
Compile MJML to HTML using Sidecar
Frequently asked questions about Mjml Sidecar
- How do I switch from mjml-php to spatie/mjml-sidecar in my Laravel app?
- Replace `Mjml::new()->toHtml($mjml)` with `Mjml::new()->sidecar()->toHtml($mjml)` in your code. No other changes are needed—just ensure the Sidecar Lambda is deployed via `php artisan sidecar:deploy --activate`. The API remains identical.
- Does spatie/mjml-sidecar support all MJML v4+ features?
- Yes, the package supports all MJML v4+ features. Sidecar’s WASM-based compiler handles the same syntax as mjml-php, so existing templates will work without modification. Test edge cases like custom components in a staging environment.
- What Laravel versions does spatie/mjml-sidecar support?
- The package is compatible with Laravel 9.x and 10.x. Ensure your PHP version is 8.1+ for WASM support. If you’re on an older Laravel version, check Sidecar’s [PHP compatibility docs](https://hammerstone.dev/sidecar/docs/main/requirements).
- How do I handle cold starts with Sidecar’s WASM initialization?
- Cold starts add ~50–100ms latency on first request. Pre-warm Sidecar by triggering a dummy compilation in `AppServiceProvider::boot()`: `MjmlSidecar::compile('<mjml>...</mjml>')`. This initializes the WASM runtime early, reducing delays for subsequent requests.
- Can I use spatie/mjml-sidecar with Laravel notifications (e.g., Mailables)?
- Absolutely. Replace `toHtml()` calls in your `Mailable` classes with the Sidecar method. For example, in `app/Mail/YourMail.php`, update the `build()` method to use `Mjml::new()->sidecar()->toHtml($this->mjml)`. Works seamlessly with `Notification` channels.
- What’s the performance difference between mjml-php and spatie/mjml-sidecar?
- Sidecar’s WASM runtime avoids PHP process overhead, offering lower latency (~20–30% faster) in high-throughput environments (e.g., bulk email sends). Benchmark your stack using Blackfire or custom latency tests to compare against mjml-php’s Node.js dependency.
- Do I need to manage Node.js or MJML binaries with this package?
- No. spatie/mjml-sidecar offloads compilation to AWS Lambda via Sidecar, eliminating the need for Node.js or MJML binaries on your servers. Deployment is handled via `php artisan sidecar:deploy`, and Spatie manages the underlying WASM runtime.
- How do I debug MJML syntax errors when using Sidecar?
- Sidecar throws exceptions for invalid MJML, similar to mjml-php. Use Laravel’s exception handler or a custom validator (e.g., `MjmlValidator`) to catch errors early. Test templates in a staging environment before production deployment to avoid runtime failures.
- Is there a fallback option if Sidecar fails in production?
- Currently, there’s no built-in fallback, but you can implement a retry mechanism or hybrid approach: use Sidecar by default and fall back to mjml-php for critical emails. Monitor Sidecar’s Lambda metrics (e.g., errors, duration) to detect issues proactively.
- How does spatie/mjml-sidecar integrate with CI/CD pipelines?
- Deployment requires AWS credentials for Lambda updates. Store them securely in your CI environment (e.g., GitHub Secrets). The `sidecar:deploy` command can be triggered in your pipeline, but ensure your AWS IAM role has permissions to update the Lambda function. Docker builds may need adjustments for WASM artifacts.
Weaver
How can I help you explore Laravel packages today?