Joystick
@joystick.js/node

Base Email Templates

How to configure base HTML and CSS templates for your emails in Joystick.

When sending email, all HTML email starts with a base template. A base template is a plain HTML file and a plain CSS file that create a standardized structure for all emails.

For individual emails, we define templates using Joystick components. At send time, Joystick injects an email template into the base template.

Base templates are similar to Joystick layout components in that they include elements and styles common to all emails (e.g., a header, a footer, etc).

By default, Joystick looks for a base HTML template at /email/base.html and a base CSS template at /email/base.css. These files are created automatically when you run joystick create <app_name>.

Example Usage

Base HTML Template

/email/base.html

&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;${subject}&lt;/title&gt;
    ${css}
  &lt;/head&gt;
  &lt;body&gt;
    &lt;span class="preheader"&gt;${preheader}&lt;/span&gt;
    &lt;div id="email"&gt;&lt;/div&gt;
  &lt;/body&gt;
&lt;/html&gt;

Required Tags in base.html

  • ${subject}: Populated with the subject value passed to email.send() when sending an email.
  • ${css}: Where Joystick injects styles from your email template components (and any child components).
  • ${preheader}: Populated with the preheader value passed to email.send() if defined (this is the preview text shown in email clients).
  • <div id="email"></div>: Where Joystick injects the rendered HTML for your email template.

Beyond these required tags, your base HTML template can include any other HTML you need.

Custom Base Templates

While it’s recommended to stick with a single base template, multiple base templates can be useful for separating marketing emails from transactional emails.

Joystick supports custom base HTML and CSS templates using the naming convention base_<custom_template_name>.html and base_<custom_template_name>.css.

To use a custom base template, call email.send() and pass the base option set to your custom template name:

email.send({
  base: 'marketing',
});

Here, Joystick will use base_marketing.html and base_marketing.css.

If the base option is omitted, Joystick defaults to base.html and base.css in the /email folder.