React Liquid Theme

A tool for building Shopify themes using React components.

---

📦 Installation

npm install react-liquid-theme

---

🚀 Usage

⚠️ Note: This package only supports ESM (ECMAScript Modules). It will not work with CommonJS.

Include this in a definition file (e.g., src/declarations.d.ts).

/// <reference types="react-liquid-theme/declarations" />

Then Run this command to generate the Shopify theme files:

# Generate liquid files from React components
npx react-liquid-theme generate

Setting up an example project

mkdir my-theme
cd my-theme
npm install react-liquid-theme
npx react-liquid-theme setup

react-liquid-theme generate Options

Option	Alias	Type	Default	Description
--source	-s	string	src	Source directory for React components
--dist	-d	string	.react-liquid	Intermediate JS output dir (add to .gitignore)
--theme	-t	string	theme	Shopify theme output directory
--watch	-w	boolean	false	Watch mode for development
--env		string	.env	Environment file
--css		string	main.css	Output CSS file name
--js		string	main.js	Output JS file name

---

📁 File Types

Use file suffixes to automatically route to Shopify theme folders, the .client.extension.ts files will be compiled to a single main.js file in the assets directory.

File Pattern	Output Directory
*.snippet.tsx	theme/snippets
*.section.tsx	theme/sections
*.template.tsx	theme/templates
*.{section,template,snippet}.client.ts	assets/main.js

---

🎨 Style Support

React Liquid Theme supports:

• CSS
• SCSS
• CSS/SCSS Modules

Import styles into React components, and they will be bundled into main.css in the theme/assets directory.

---

🧹 Built-in Components

These React components map to Liquid tags or control flow logic:

Component	Description
LiquidAssign	{% assign %}
LiquidBreak	{% break %}
LiquidCapture	{% capture %}
LiquidContinue	{% continue %}
LiquidFor	{% for %}
LiquidIf	{% if %}
LiquidUnless	{% unless %}
LiquidStatement	{% liquid %}
LiquidExpression	{{ expression }}
LiquidTag	Can create any tag

---

🧪 Requirements

• Node.js ≥ 20
• Peer dependencies:
  • react ≥ 19
  • react-dom ≥ 19
  • typescript ≥ 5.8
  • sass >= 1

---

📝 License

MIT