React Email Shopify Liquid

Create shopify notification emails with a combination of React and Liquid

Table of Contents

• Getting Started
• Example templates
• Images
• Custom Fonts
• Important Notes

Problem

You are building a headless ecommerce experience using shopify. Probably with Hydrogen, Remix, NextJS, etc.

You've built a set of composable components using React, however there is one critical piece that is missing: Email Notifications. Emails for Order confirmation, shipping, etc.

You'll need to use Shopify's Liquid to build all of your email templates, which is a completely different developer experience than React.

This Solution

We've build a set of components using React Email to help you create beautiful email templates. Helping consolidate the developer experience when creating headless shopify store.

Getting Started

In your project directory:

1. Install: pnpm add react-email @react-email/components react-email-shopify-liquid -E

2. Create an emails folder at the top level of your project directory.

3. Create a file named OrderConfirmation.tsx and paste the following:

   This template is from examples/emails/OrderConfirmation.tsx:

   import React from 'react';
   import { Hr, Preview, Section, Text } from '@react-email/components';
   import { EmailContainer, Greeting, OrderLineItems, OrderStatusLink, OrderTransactions, PaymentTerms, ShippingAddress, Subtotals } from 'react-email-shopify-liquid';
   
   export const OrderConfirmation = () => (
       <EmailContainer>
           <Preview>Order Confirmation</Preview>
           <Section>
               <Greeting />
               <Text>
                   Thank you for placing your order ({'{{ order.name }}'}). As soon as your order ships, you will receive a separate shipping confirmation email with tracking information.
               </Text>
           </Section>
           <Section className="mt-6">
               <OrderStatusLink />
           </Section>
           <Hr className="border-black my-10"></Hr>
           <OrderLineItems />
           <Subtotals />
           <Hr className="border-black my-10"></Hr>
           <PaymentTerms />
           <OrderTransactions />
           <ShippingAddress />
       </EmailContainer>
   );
   
   export default OrderConfirmation;

4. Add the following script to your package.json which will generate the email template html files

   "email:export": "email export && decode-entities"
   

   This package includes a simple decode-entities bin script. React will encode things like quotes and >, <, which might be used within liquid expressins into html entites. Hence we need to decode those for liquid to render properly.

   Example: Payment of {{ order.total_outstanding | money }} is due {{ due_date | date: format: 'date' }} will become Payment of {{ order.total_outstanding | money }} is due {{ due_date | date: format: 'date' }} once decoded.

Decode entities advanced usage

1. If you have a more complex workflow, create your own script to handle decoding the html files.

   #!/usr/bin/env node
   import { readFileSync, writeFileSync } from 'fs';
   import path from 'path';
   import { glob } from 'glob';
   import { decode } from 'html-entities';
   
   // React will encode quotes and etc that might be used within liquid expressions into entites.
   // Hence we need to decode those for liquid to render properly
   export const decodeEntities = () => {
       const generatedEmailPaths = glob.sync(path.join(process.cwd(), 'out', '**/*.html'))
   
       for (const emailPath of generatedEmailPaths) {
           const html = decode(readFileSync(emailPath, { 'encoding': 'utf-8' }));
           writeFileSync(emailPath, html, { encoding: 'utf-8' });
       }
   };
   
   decodeEntities();

5. Run the script pnpm run email:export. And look in the new folder out that was created.

   • This command will create a new directory out at the root level of your project. All of the generated html files for your email templates will be placed here. See react-email documentation for more information on the email export command. The default source directory for your templates is emails.
   

6. Let's preview the email template: Head over to the shopify admin page.

7. Click on the Settings ⚙️ icon

   

8. Select the Notifications menu item

   

9. Click on the Customer Notifications menu item

   

10. Select the Order Confirmation notification

    

11. Hit the Edit Code button

    

12. Paste the generated html from OrderConfirmation.html into the textarea

    

13. Preview your changes and hit save.

    Can I preview my email templates with react-email's email:dev script? Yes, but it won't be that helpful. Since the templates include liquid template syntax for retrieving like order details, line items, product information, we need these objects provided to us.

    Shopify's email template preview functionality will actually render your email template using the liquid template engine and provide all the relevant objects like order, product, etc. The email:dev script would just render the raw liquid syntax.

14. That's it. Now, repeat for the rest of your email templates! Head over to examples/emails to see more templates.

Provided Example Templates

Template
ContactCustomer.tsx
DraftOrderInvoice.tsx
OrderCanceled.tsx
OrderConfirmation.tsx
OrderInvoice.tsx
OrderPaymentReceipt.tsx
OrderRefund.tsx
OrderUpdated.tsx
PaymentError.tsx
PaymentReminder.tsx
PaymentSuccess.tsx
ShippingConfirmation.tsx
ShippingDelivered.tsx
ShippingOutForDelivery.tsx
ShippingUpdated.tsx

Images

1. You should either upload images to shopify as files, aws s3, or any other type of CDN.

2. Then use the CDN urls in the react-email Image component within the template.

       <Img src="https://some.cdn.com/image.png" width="76"/>

Custom Fonts

1. You should either upload your custom font to shopify as files, aws s3, or any other type of CDN.

2. Then use the CDN urls in the react-email Font component within the template.

3. See the react-email docs on how to use the Font component.

   <Font fallbackFontFamily={['Helvetica']}
       fontFamily="MyCustomFont"
       webFont={{
           url: 'https://cdn.shopify.com/s/files/.../my-custom-font.woff2',
           format: 'woff2'
       }}
       fontWeight={400}
       fontStyle="normal"/>

Important Notes

If you take a look at the default shopify email templates available in shopify admin, you'll see there is a lot of logic involved. Not every single piece of logic is ported over to this package. If any custom logic is required, just create your own component using our provided Liquid components. See the example templates for how this can be done.