Class MjmlRenderer

java.lang.Object
dev.jcputney.mjml.MjmlRenderer
public final class MjmlRenderer extends Object
Public API entry point for rendering MJML templates to HTML.

Thread safety: Both the static render() methods and the instance API are thread-safe. Each render call creates its own GlobalContext, so concurrent calls do not share mutable state. The provided MjmlConfiguration is immutable and safe to share.

Usage

// One-liner with defaults (convenience, creates a new pipeline each time)
MjmlRenderResult result = MjmlRenderer.render(mjmlString);
String html = result.html();

// Instance API (preferred for repeated rendering — reuses the pipeline)
MjmlRenderer renderer = MjmlRenderer.create(config);
MjmlRenderResult r1 = renderer.renderTemplate(mjml1);
MjmlRenderResult r2 = renderer.renderTemplate(mjml2);

  • Method Details

    • create

      public static MjmlRenderer create(MjmlConfiguration configuration)
      Creates a reusable renderer instance with the given configuration. The instance caches and reuses the internal RenderPipeline and ComponentRegistry, making it significantly faster for repeated rendering than the static convenience methods.

      This is the preferred API when rendering multiple templates with the same configuration.

      Parameters:
      configuration - the rendering configuration
      Returns:
      a reusable renderer instance

    • create

      public static MjmlRenderer create()
      Creates a reusable renderer instance with default configuration.
      Returns:
      a reusable renderer instance

    • render

      public static MjmlRenderResult render(String mjml)
      Renders an MJML template to HTML using default configuration.

      For repeated rendering, prefer the instance API via create(MjmlConfiguration).

      Parameters:
      mjml - the MJML source string
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if parsing or rendering fails

    • render

      public static MjmlRenderResult render(String mjml, MjmlConfiguration configuration)
      Renders an MJML template to HTML with the given configuration.

      For repeated rendering, prefer the instance API via create(MjmlConfiguration).

      Parameters:
      mjml - the MJML source string
      configuration - the rendering configuration
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if parsing or rendering fails

    • render

      public static MjmlRenderResult render(Path mjmlFile)
      Renders an MJML file to HTML using default configuration. Automatically configures a file system include resolver using the file's parent directory.

      For repeated rendering, prefer the instance API via create(MjmlConfiguration).

      Parameters:
      mjmlFile - path to the MJML file
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if reading, parsing, or rendering fails

    • render

      public static MjmlRenderResult render(Path mjmlFile, MjmlConfiguration configuration)
      Renders an MJML file to HTML with the given configuration. If no include resolver is configured, one is automatically created using the file's parent directory.

      For repeated rendering, prefer the instance API via create(MjmlConfiguration).

      Parameters:
      mjmlFile - path to the MJML file
      configuration - the rendering configuration
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if reading, parsing, or rendering fails

    • renderTemplate

      public MjmlRenderResult renderTemplate(String mjml)
      Renders an MJML template to HTML using this instance's configuration.
      Parameters:
      mjml - the MJML source string
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if parsing or rendering fails

    • renderTemplate

      public MjmlRenderResult renderTemplate(Path mjmlFile)
      Renders an MJML file to HTML using this instance's configuration. If no include resolver is configured, one is automatically created using the file's parent directory.
      Parameters:
      mjmlFile - path to the MJML file
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if reading, parsing, or rendering fails

    • renderTemplate

      public MjmlRenderResult renderTemplate(String mjml, IncludeResolver resolver)
      Renders an MJML template to HTML with a specific include resolver, overriding the instance's configured resolver for this call only.
      Parameters:
      mjml - the MJML source string
      resolver - the include resolver to use
      Returns:
      the render result containing HTML and metadata
      Throws:
      MjmlException - if parsing or rendering fails