🚀 Reactpify

The ultimate React integration library for Shopify themes. Build modern, interactive components with React while maintaining perfect SEO and theme compatibility.

✨ Features

🔄 Automatic Liquid Generation

• React → Liquid: Automatically generates Shopify Liquid templates from your React components
• SEO-friendly fallbacks: HTML shells rendered server-side for perfect SEO
• Theme Editor compatibility: Components work seamlessly in Shopify's theme customizer

🎨 Intelligent Theme Integration

• Automatic Style Analysis: Detects and extracts original theme styles
• Perfect Scoping: CSS automatically scoped to avoid conflicts with existing theme
• Tailwind Integration: Full Tailwind CSS v4 support with theme-aware configuration

👀 Bidirectional Watch System

• React → Liquid Sync: Changes in React components automatically update Liquid files
• Manual Edit Detection: Detects when Liquid files are manually modified
• Real-time Updates: Vite-powered development with instant hot reloading

🧩 Fragment System

• Reusable Snippets: Share common Liquid schema fragments across components
• Auto-injection: Fragments automatically injected during build process
• Extensible: Easy to add custom fragments for your specific needs

📋 Prerequisites

Reactpify installs ON TOP of existing Shopify themes. Before installing, you need:

🏪 Existing Shopify Theme

• A working Shopify theme directory with these folders:

  your-theme/
  ├── assets/
  ├── layout/
  ├── sections/
  ├── snippets/
  └── templates/

🎯 Compatible Themes

• ✅ Dawn (Shopify's free theme)
• ✅ Horizon (Latest Shopify theme)
• ✅ Any modern Shopify theme (Online Store 2.0+)
• ✅ Custom themes with standard structure

🚀 How to Get a Shopify Theme

Option 1: Download from your Shopify store

# Install Shopify CLI
npm install -g @shopify/cli @shopify/theme

# Download your live theme
shopify theme pull

# Or start with Dawn (free theme)
shopify theme init my-theme --clone-url="https://github.com/Shopify/dawn"

Option 2: Use an existing theme directory If you already have a Shopify theme folder, navigate to it:

cd your-existing-theme/
# Now you can install Reactpify

🚀 Quick Start

Installation

⚠️ Important: Run this command INSIDE your Shopify theme directory

cd your-theme-folder/
npm install reactpifyjs

Reactpify will automatically:

• ✅ Detect your Shopify theme
• ✅ Install all necessary files
• ✅ Update layout/theme.liquid
• ✅ Create example components
• ✅ Set up the build system

Basic Usage

1. Create a React Component

// src/components/hello/Hello.tsx
import React, { useState } from 'react';

interface HelloProps {
  title?: string;
  showButton?: boolean;
}

export const Hello: React.FC<HelloProps> = ({
  title = "Hello World",
  showButton = true
}) => {
  const [clicked, setClicked] = useState(false);

  return (
    <div className="reactpify-container max-w-md mx-auto p-6">
      <div className="bg-blue-500 text-white p-6 rounded-lg shadow-lg text-center">
        <h1 className="text-2xl font-bold mb-4">{title}</h1>
        
        {showButton && (
          <button 
            onClick={() => setClicked(!clicked)}
            className="bg-white text-blue-500 px-4 py-2 rounded hover:bg-gray-100 transition-colors font-semibold"
          >
            {clicked ? '✅ Clicked!' : '👋 Click me'}
          </button>
        )}
      </div>
    </div>
  );
};

2. Create the Liquid Template

<!-- src/components/hello/section.hello.liquid -->
{% comment %}
Auto-generated by Reactpify
Component: Hello
{% endcomment %}

<div data-component-root data-section-data='{{ section | json | escape }}'>
  <div data-fallback>
    <div class="max-w-md mx-auto p-6">
      <div class="bg-blue-500 text-white p-6 rounded-lg shadow-lg text-center">
        <h1 class="text-2xl font-bold mb-4">{{ section.settings.title | default: 'Hello World' }}</h1>
        
        {% if section.settings.show_button %}
          <button class="bg-white text-blue-500 px-4 py-2 rounded font-semibold">
            👋 Click me
          </button>
        {% endif %}
      </div>
    </div>
  </div>
</div>

{{ 'main.css' | asset_url | stylesheet_tag }}
{{ 'main.js' | asset_url | script_tag }}

{% schema %}
{
  "name": "Hello",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "Hello World"
    },
    {
      "type": "checkbox",
      "id": "show_button",
      "label": "Show Button",
      "default": true
    },
    FRAGMENT.color-scheme,
    FRAGMENT.section-spacing
  ],
  "presets": [
    {
      "name": "Hello"
    }
  ]
}
{% endschema %}

3. Register Your Component

// src/main.tsx
import { registerComponent, initRenderSystem } from './utils/helpers/renderComponents';
import { Hello } from './components/hello/Hello';

registerComponent('Hello', Hello);
initRenderSystem();

4. Build and Deploy

npm run build    # Production build
npm run watch    # Development with auto-reload

🛠 Advanced Features

Theme Style Analyzer

Automatically analyzes your existing Shopify theme styles and integrates them seamlessly:

# Automatically runs on first build
npm run build

What it does:

• 🔍 Scans assets/*.css for theme styles
• 🎯 Extracts important selectors (:root, .shopify-*, @keyframes, etc.)
• 🛡️ Scopes styles to avoid conflicts with React components
• 📄 Searches for embedded CSS in Liquid files
• 💾 Generates src/styles/theme-extracted.css automatically

Bidirectional Watch System

Monitor changes in both directions:

npm run watch

Features:

• 👁️ Watches React component changes → Auto-updates Liquid
• 🔧 Detects manual Liquid file modifications
• ⚡ Real-time synchronization
• 🚫 Prevents infinite loops with smart debouncing

Fragment System

Create reusable Liquid schema fragments:

<!-- src/utils/schema-fragments/custom-colors.liquid -->
{
  "type": "select",
  "id": "custom_color",
  "label": "Custom Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

Use in your components:

{% schema %}
{
  "settings": [
    FRAGMENT.custom-colors,
    FRAGMENT.color-scheme
  ]
}
{% endschema %}

📁 Project Structure

your-theme/
├── src/
│   ├── components/
│   │   └── hello/
│   │       ├── Hello.tsx              # React component
│   │       └── section.hello.liquid   # Liquid template
│   ├── styles/
│   │   ├── main.css                   # Main styles
│   │   └── theme-extracted.css        # Auto-generated theme styles
│   ├── utils/
│   │   └── schema-fragments/          # Reusable Liquid fragments
│   └── main.tsx                       # Entry point
├── sections/
│   └── hello.liquid                   # Auto-copied from src/
├── assets/
│   ├── main.css                       # Built CSS
│   └── main.js                        # Built JS
└── vite.config.ts                     # Vite configuration

⚙️ Configuration

Vite Configuration

The library includes a pre-configured Vite setup optimized for Shopify:

// vite.config.ts - Already configured!
export default defineConfig(({ mode }) => ({
  // ✅ Theme Style Analyzer
  // ✅ Bidirectional Watch
  // ✅ Auto Component Registry
  // ✅ Fragment Injection
  // ✅ Tailwind CSS v4
  // ✅ CSS Extraction
  // ✅ Asset Optimization
}));

Tailwind Configuration

Fully configured with theme-aware settings:

// tailwind.config.js - Already configured!
export default {
  content: [
    './src/**/*.{ts,tsx}',
    './src/components/**/*.liquid',
    './sections/**/*.liquid'
  ],
  // ✅ Scoped to [data-component-root]
  // ✅ Preflight disabled
  // ✅ Custom Reactpify variables
  // ✅ Animation safelist
};

🎯 Best Practices

1. Component Structure

• Keep components in src/components/[name]/
• Use consistent naming: ComponentName.tsx + section.component-name.liquid
• Always provide fallback HTML for SEO

2. Styling

• Use Tailwind classes for consistency
• Scope custom CSS with .reactpify-* classes
• Leverage CSS variables for theme integration

3. Liquid Templates

• Include data-component-root for React mounting
• Provide meaningful fallback content
• Use fragments for common schema patterns

4. Development Workflow

• Use npm run watch for development
• Test both JavaScript-enabled and disabled scenarios
• Verify theme customizer compatibility

🚀 Production Deployment

# Build for production
npm run build

# Files generated:
# ✅ assets/main.css - All styles combined
# ✅ assets/main.js - React components bundle
# ✅ sections/*.liquid - Updated Liquid templates

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

MIT License - see LICENSE file for details.

🆘 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the Shopify community