{"id":21826120,"url":"https://github.com/snowdiamonds/react-email-shopify-liquid","last_synced_at":"2025-10-08T04:30:58.574Z","repository":{"id":232870183,"uuid":"784390353","full_name":"snowdiamonds/react-email-shopify-liquid","owner":"snowdiamonds","description":"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.","archived":false,"fork":false,"pushed_at":"2024-04-25T16:57:09.000Z","size":190,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-04T18:43:46.685Z","etag":null,"topics":["email","javascript","react","react-email","react-email-component","shopify","shopify-theme","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snowdiamonds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-09T18:52:11.000Z","updated_at":"2024-11-18T10:41:54.000Z","dependencies_parsed_at":"2024-04-25T17:55:19.649Z","dependency_job_id":null,"html_url":"https://github.com/snowdiamonds/react-email-shopify-liquid","commit_stats":null,"previous_names":["snowdiamonds/react-email-shopify-liquid"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowdiamonds%2Freact-email-shopify-liquid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowdiamonds%2Freact-email-shopify-liquid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowdiamonds%2Freact-email-shopify-liquid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowdiamonds%2Freact-email-shopify-liquid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snowdiamonds","download_url":"https://codeload.github.com/snowdiamonds/react-email-shopify-liquid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235679180,"owners_count":19028323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","javascript","react","react-email","react-email-component","shopify","shopify-theme","typescript"],"created_at":"2024-11-27T18:03:20.083Z","updated_at":"2025-10-08T04:30:53.271Z","avatar_url":"https://github.com/snowdiamonds.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Email Shopify Liquid\n\n\u003e Create shopify notification emails with a combination of React and Liquid\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/8a7fe588-c2e7-4a67-958a-02014efeb539\" width=\"400\" /\u003e    \n\u003c/p\u003e\n\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Example templates](examples/emails)\n- [Images](#images)\n- [Custom Fonts](#custom-fonts)\n- [Important Notes](#important-notes)\n\n## Problem\n\nYou are building a headless ecommerce experience using shopify. Probably with Hydrogen, Remix, NextJS, etc. \n\nYou'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.\n\nYou'll need to use Shopify's `Liquid` to build all of your email templates, which is a completely different developer experience than React. \n\n## This Solution\n\nWe'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.\n\n## Getting Started\n\n**In your project directory:**\n\n1. Install: `pnpm add react-email @react-email/components react-email-shopify-liquid -E`\n2. Create an `emails` folder at the top level of your project directory.\n3. Create a file named `OrderConfirmation.tsx` and paste the following: \n\n    \u003e This template is from [`examples/emails/OrderConfirmation.tsx`](examples/emails/OrderConfirmation.tsx):\n\n    ```jsx\n    import React from 'react';\n    import { Hr, Preview, Section, Text } from '@react-email/components';\n    import { EmailContainer, Greeting, OrderLineItems, OrderStatusLink, OrderTransactions, PaymentTerms, ShippingAddress, Subtotals } from 'react-email-shopify-liquid';\n\n    export const OrderConfirmation = () =\u003e (\n        \u003cEmailContainer\u003e\n            \u003cPreview\u003eOrder Confirmation\u003c/Preview\u003e\n            \u003cSection\u003e\n                \u003cGreeting /\u003e\n                \u003cText\u003e\n                    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.\n                \u003c/Text\u003e\n            \u003c/Section\u003e\n            \u003cSection className=\"mt-6\"\u003e\n                \u003cOrderStatusLink /\u003e\n            \u003c/Section\u003e\n            \u003cHr className=\"border-black my-10\"\u003e\u003c/Hr\u003e\n            \u003cOrderLineItems /\u003e\n            \u003cSubtotals /\u003e\n            \u003cHr className=\"border-black my-10\"\u003e\u003c/Hr\u003e\n            \u003cPaymentTerms /\u003e\n            \u003cOrderTransactions /\u003e\n            \u003cShippingAddress /\u003e\n        \u003c/EmailContainer\u003e\n    );\n\n    export default OrderConfirmation;\n    ```\n\n4. Add the following script to your `package.json` which will generate the email template html files\n\n    ```\n    \"email:export\": \"email export \u0026\u0026 decode-entities\"\n    ```\n\n    \u003e This package includes a simple `decode-entities` bin script. React will encode things like quotes and `\u003e`, `\u003c`, which might be used within liquid expressins into html entites. Hence we need to decode those for liquid to render properly.\n\n    \u003e Example: `Payment of {{ order.total_outstanding | money }} is due {{ due_date | date: format: \u0026#x27;date\u0026#x27; }}` will become `Payment of {{ order.total_outstanding | money }} is due {{ due_date | date: format: 'date' }}` once decoded.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eDecode entities advanced usage\u003c/summary\u003e\n\n1. If you have a more complex workflow, create your own script to handle decoding the html files.\n    \n    ```javascript\n    #!/usr/bin/env node\n    import { readFileSync, writeFileSync } from 'fs';\n    import path from 'path';\n    import { glob } from 'glob';\n    import { decode } from 'html-entities';\n\n    // React will encode quotes and etc that might be used within liquid expressions into entites.\n    // Hence we need to decode those for liquid to render properly\n    export const decodeEntities = () =\u003e {\n        const generatedEmailPaths = glob.sync(path.join(process.cwd(), 'out', '**/*.html'))\n\n        for (const emailPath of generatedEmailPaths) {\n            const html = decode(readFileSync(emailPath, { 'encoding': 'utf-8' }));\n            writeFileSync(emailPath, html, { encoding: 'utf-8' });\n        }\n    };\n\n    decodeEntities();\n    ```\n\u003c/details\u003e\n\n\n5. Run the script `pnpm run email:export`. And look in the new folder `out` that was created. \n    -  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`.\n\n\n    \u003cimg width=\"629\" alt=\"Screenshot 2024-04-22 at 11 43 30 AM\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/2c905381-c372-494f-bff4-6697a4769ff5\"\u003e\n\n6. **Let's preview the email template:** Head over to the shopify admin page.\n\n7. Click on the `Settings` ⚙️ icon\n\n    \u003cimg width=\"336\" alt=\"step-1\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/185570ea-b17d-4914-963c-e523e83c2f4c\"\u003e\n\n8. Select the `Notifications` menu item\n\n    \u003cimg width=\"345\" alt=\"step-2\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/bcfea313-043e-45c7-8fae-3bd7698a45b4\"\u003e\n\n9. Click on the `Customer Notifications` menu item\n\n    \u003cimg width=\"809\" alt=\"step-3\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/959c95fb-cb73-47bc-b50c-db7c4e241b1c\"\u003e\n\n10. Select the `Order Confirmation` notification\n\n    \u003cimg width=\"785\" alt=\"step-4\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/ccb541f9-45ac-48a9-8a72-cf072a3e97d7\"\u003e\n\n11. Hit the `Edit Code` button\n\n    \u003cimg width=\"917\" alt=\"step-5\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/b0e334c9-b801-4ca3-a061-606cdddb86f7\"\u003e\n\n12. Paste the generated html from `OrderConfirmation.html` into the textarea\n\n    \u003cimg width=\"827\" alt=\"step-6\" src=\"https://github.com/snowdiamonds/react-email-shopify-liquid/assets/1103708/61a23a35-d7cb-48c3-b345-e8e0b1a41759\"\u003e\n\n\n13. Preview your changes and hit save.\n\n    \u003e 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. \n\n    \u003e 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.\n\n14. **That's it.** Now, repeat for the rest of your email templates! Head over to [`examples/emails`](examples/emails) to see more templates.\n\n## Provided Example Templates\n\n| Template                                         |\n|--------------------------------------------------|\n| [`ContactCustomer.tsx`](examples/emails/)        |\n| [`DraftOrderInvoice.tsx`](examples/emails/)      |\n| [`OrderCanceled.tsx`](examples/emails/)          |\n| [`OrderConfirmation.tsx`](examples/emails/)      |\n| [`OrderInvoice.tsx`](examples/emails/)           |\n| [`OrderPaymentReceipt.tsx`](examples/emails/)    |\n| [`OrderRefund.tsx`](examples/emails/)            |\n| [`OrderUpdated.tsx`](examples/emails/)           |\n| [`PaymentError.tsx`](examples/emails/)           |\n| [`PaymentReminder.tsx`](examples/emails/)        |\n| [`PaymentSuccess.tsx`](examples/emails/)         |\n| [`ShippingConfirmation.tsx`](examples/emails/)   |\n| [`ShippingDelivered.tsx`](examples/emails/)      |\n| [`ShippingOutForDelivery.tsx`](examples/emails/) |\n| [`ShippingUpdated.tsx`](examples/emails/)        |\n\n## Images\n\n1. You should either upload images to shopify as files, aws s3, or any other type of CDN.\n2. Then use the CDN urls in the react-email `Image` component within the template.\n\n    ```jsx\n        \u003cImg src=\"https://some.cdn.com/image.png\" width=\"76\"/\u003e\n    ```\n\n## Custom Fonts\n\n1. You should either upload your custom font to shopify as files, aws s3, or any other type of CDN.\n2. Then use the CDN urls in the react-email `Font` component within the template.\n3. See the react-email docs on how to use the `Font` component.\n\n    ```jsx\n    \u003cFont fallbackFontFamily={['Helvetica']}\n        fontFamily=\"MyCustomFont\"\n        webFont={{\n            url: 'https://cdn.shopify.com/s/files/.../my-custom-font.woff2',\n            format: 'woff2'\n        }}\n        fontWeight={400}\n        fontStyle=\"normal\"/\u003e\n    ```\n\n## Important Notes\n\nIf 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowdiamonds%2Freact-email-shopify-liquid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnowdiamonds%2Freact-email-shopify-liquid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowdiamonds%2Freact-email-shopify-liquid/lists"}