Mjml-custom-component-decorator NPM

mjml-custom-component-decorator

Features

Define custom MJML components with TypeScript decorator
Automatic discovery and registration on file load

Requirements

Installation

npm i --save mjml-custom-component-decorator

Usage

TypeScript

First of all, you will need to enable experimental decorators in your tsconfig:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Then you can use it as simple as this:

import {BodyComponent, registerComponent} from "mjml-core";
import {registerDependencies} from "mjml-validator";

import {MJMLCustomComponent} from "mjml-custom-component-decorator";

@MJMLCustomComponent({
    tag: "my-custom-component",
    attributes: {
        text: {
            type: 'string',
            default: 'Hello World'
        }
    },
    allowedParentTags: ["mj-column"],
})
export class MyCustomComponent extends BodyComponent {
    render() {
        return this.renderMJML(`
            <mj-text>
                Hello there, this is what you gave as text attribute: ${this.getAttribute("text")}
            </mj-text>`
        )
    }
}

Motivation

When you are developing custom components in mjml you will find yourself writing the same boilerplate code over and over again. It gets even worse, because you need to define some static properties without any kind of autocomplete.

This is where typescript and its decorator features come handy. You write the decorator, and the project simply intercepts the class and adds the required fields. To make it even easier, TypeScript enables you to use the autocomplete of your favourite IDE, isn't that awesome?!

Just for completeness without the decorator ...

... it looks like this:

import {registerDependencies} from "mjml-validator"
import {registerComponent} from "mjml-core";

export class MyCustomComponent extends BodyComponent {
    static allowedAttributes = {
        text: 'string'
    }

    static defaultAttributes = {
        'text': 'Hello World'
    }

    static endingTag = false

    render() {
        return this.renderMJML(`
            <mj-text>
                Hello there, this is what you gave as text attribute: ${this.getAttribute("text")}
            </mj-text>`
        )
    }
}

registerComponent(MyCustomComponent)
registerDependencies({
    'mj-column': ['my-custom-component'],
    'my-custom-component': []
})

You duplicate your attribute name twice and can't have some kind of defaults (excerpt using inheritance)