Registry / ecommerce / vite-plugin-react-shopify

vite-plugin-react-shopify

library2.2.9jsnpmunverified

A Vite plugin that enables developers to build Shopify themes using React components. It compiles React sections, blocks, snippets, and templates into Shopify Liquid files at build time via SSG (Static Site Generation). The runtime handles hydration, providing a full React development experience while maintaining Shopify compatibility. Current version 2.2.9 requires Vite ^8.0.0. Three key differentiators: (1) AI-friendly — developers can leverage React/TypeScript which LLMs understand better than Liquid; (2) testability — React components can be unit-tested with Jest/Vitest; (3) modern tooling — TypeScript, tree-shaking, and component-based architecture. Actively maintained on GitHub with weekly release cadence.

ecommerce devops

npm install vite-plugin-react-shopify

package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-REACT-

vite-plugin-react-shopify

ecommercejavascriptv2.2.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import vitePluginShopify from 'vite-plugin-react-shopify'

✗ const vitePluginShopify = require('vite-plugin-react-shopify')

Package is ESM-only. CommonJS require is not supported and will throw.

ShopifyMeta

✓ import type { ShopifyMeta } from 'vite-plugin-react-shopify'

✗ import { ShopifyMeta } from 'vite-plugin-react-shopify'

ShopifyMeta is a type, use type-only import to avoid runtime errors.

useSectionSettings

✓ import { useSectionSettings } from 'vite-plugin-react-shopify/runtime'

✗ import { useSectionSettings } from 'vite-plugin-react-shopify'

Runtime hooks are exported from 'vite-plugin-react-shopify/runtime' subpath, not the main entry.

Configures Vite plugin and defines a Shopify section component with settings.

// vite.config.ts import { defineConfig } from 'vite'; import vitePluginShopify from 'vite-plugin-react-shopify'; export default defineConfig({ plugins: [ vitePluginShopify({ sourceCodeDir: 'frontend', }), ], }); // frontend/sections/HelloWorld.tsx import type { ShopifyMeta } from 'vite-plugin-react-shopify'; import { useSectionSettings } from 'vite-plugin-react-shopify/runtime'; export const shopifyMeta = { name: 'Hello World', settings: [ { type: 'text', id: 'title', label: 'Title', default: 'Hello, World!' }, ], presets: [{ name: 'Hello World' }], } satisfies ShopifyMeta; export default function HelloWorld() { const { value: title } = useSectionSettings('title'); return <h1>{title}</h1>; } // Run: pnpm dev (starts Vite build watch)

Debug

Known issues

breakingVersion 2.x requires Vite 8. Using with Vite 5 or 7 will cause plugin initialization failure.

fix

Upgrade Vite to ^8.0.0 or stick with v1.x of the plugin.

affects: >=2.0.0

breakingRuntime hooks moved from main entry to subpath 'vite-plugin-react-shopify/runtime' in v2. Direct imports from 'vite-plugin-react-shopify' will be undefined.

fix

Change imports: import { useSectionSettings } from 'vite-plugin-react-shopify/runtime'

affects: >=2.0.0

deprecatedThe 'prefix' option in ssg config is deprecated. Use 'ssg.prefix' object keys instead of string.

fix

Use ssg: { prefix: { section: 'r-', ... } }

affects: >=2.2.0

gotchaCSS extraction: Shared component CSS (from e.g. frontend/components/) is automatically extracted into separate Liquid files. If your shared CSS is not appearing, ensure the component is imported from the correct relative path.

fix

Place shared components in frontend/components/ and import them with relative paths like './components/SharedCard'.

affects: >=1.0.0

gotchaFile naming: Generated Liquid files use 'react-' prefix by default. If your theme already has files with that prefix, they may conflict or be overwritten.

fix

Configure a custom prefix in ssg.prefix to avoid name collisions.

affects: >=1.0.0

gotchaHydration: Components that rely on browser-only APIs (window, document) will fail during SSG build. Wrap them in useEffect or dynamic import.

fix

Use useEffect or lazy loading for browser-specific logic.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'vite-plugin-react-shopify/runtime' or its corresponding type declarations.

Using an older version (<2.0.0) that didn't have the runtime subpath.

fix

Upgrade to v2.2.9: pnpm add vite-plugin-react-shopify@latest

Error: [vite-plugin-react-shopify] Vite version 7.x is not supported. Please upgrade to Vite 8.

Plugin v2 requires Vite 8 as peer dependency.

fix

Upgrade Vite to ^8.0.0: pnpm add vite@^8.0.0

TypeError: plugin is not a function

Using CommonJS require to import the ESM-only module.

fix

Change to ES module import: import vitePluginShopify from 'vite-plugin-react-shopify'

Module not found: Error: Can't resolve 'react' in '/path/to/frontend'

Missing peer dependency react or react-dom.

fix

Install react and react-dom: pnpm add react react-dom

Upgrade

Version history

2.2.9latest on npm

Audit

Dependencies

viterequiredPeer dependency; requires Vite 8 or higher for build plugin functionality.

Agent activity

36 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagevite-plugin-react-shopify ↗