https://github.com/snowdiamonds/react-email-shopify-liquid
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.
https://github.com/snowdiamonds/react-email-shopify-liquid
email javascript react react-email react-email-component shopify shopify-theme typescript
Last synced: 10 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/snowdiamonds/react-email-shopify-liquid
- Owner: snowdiamonds
- License: mit
- Created: 2024-04-09T18:52:11.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-25T16:57:09.000Z (over 2 years ago)
- Last Synced: 2024-12-04T18:43:46.685Z (over 1 year ago)
- Topics: email, javascript, react, react-email, react-email-component, shopify, shopify-theme, typescript
- Language: TypeScript
- Homepage:
- Size: 186 KB
- Stars: 11
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Email Shopify Liquid
> Create shopify notification emails with a combination of React and Liquid
## Table of Contents
- [Getting Started](#getting-started)
- [Example templates](examples/emails)
- [Images](#images)
- [Custom Fonts](#custom-fonts)
- [Important Notes](#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`](examples/emails/OrderConfirmation.tsx):
```jsx
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 = () => (
Order Confirmation
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.
);
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.
```javascript
#!/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`](examples/emails) to see more templates.
## Provided Example Templates
| Template |
|--------------------------------------------------|
| [`ContactCustomer.tsx`](examples/emails/) |
| [`DraftOrderInvoice.tsx`](examples/emails/) |
| [`OrderCanceled.tsx`](examples/emails/) |
| [`OrderConfirmation.tsx`](examples/emails/) |
| [`OrderInvoice.tsx`](examples/emails/) |
| [`OrderPaymentReceipt.tsx`](examples/emails/) |
| [`OrderRefund.tsx`](examples/emails/) |
| [`OrderUpdated.tsx`](examples/emails/) |
| [`PaymentError.tsx`](examples/emails/) |
| [`PaymentReminder.tsx`](examples/emails/) |
| [`PaymentSuccess.tsx`](examples/emails/) |
| [`ShippingConfirmation.tsx`](examples/emails/) |
| [`ShippingDelivered.tsx`](examples/emails/) |
| [`ShippingOutForDelivery.tsx`](examples/emails/) |
| [`ShippingUpdated.tsx`](examples/emails/) |
## 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.
```jsx
```
## 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.
```jsx
```
## 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](examples/emails) for how this can be done.