Skip to content

If you're building headless Shopify stores, you're probably already using React. This package helps you continue using React for building customer notification emails.

License

Notifications You must be signed in to change notification settings

snowdiamonds/react-email-shopify-liquid

Repository files navigation

React Email Shopify Liquid

Create shopify notification emails with a combination of React and Liquid

Table of Contents

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: &#x27;date&#x27; }} 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();
  1. 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.
    Screenshot 2024-04-22 at 11 43 30 AM
  2. Let's preview the email template: Head over to the shopify admin page.

  3. Click on the Settings ⚙️ icon

    step-1
  4. Select the Notifications menu item

    step-2
  5. Click on the Customer Notifications menu item

    step-3
  6. Select the Order Confirmation notification

    step-4
  7. Hit the Edit Code button

    step-5
  8. Paste the generated html from OrderConfirmation.html into the textarea

    step-6
  9. 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.

  10. 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.

About

If you're building headless Shopify stores, you're probably already using React. This package helps you continue using React for building customer notification emails.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published