{"id":42244,"library":"vite-plugin-react-shopify","title":"Vite Plugin React Shopify","description":"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.","status":"active","version":"2.2.9","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install vite-plugin-react-shopify","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-react-shopify","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-react-shopify","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; requires Vite 8 or higher for build plugin functionality.","package":"vite","optional":false}],"imports":[{"note":"Package is ESM-only. CommonJS require is not supported and will throw.","wrong":"const vitePluginShopify = require('vite-plugin-react-shopify')","symbol":"default","correct":"import vitePluginShopify from 'vite-plugin-react-shopify'"},{"note":"ShopifyMeta is a type, use type-only import to avoid runtime errors.","wrong":"import { ShopifyMeta } from 'vite-plugin-react-shopify'","symbol":"ShopifyMeta","correct":"import type { ShopifyMeta } from 'vite-plugin-react-shopify'"},{"note":"Runtime hooks are exported from 'vite-plugin-react-shopify/runtime' subpath, not the main entry.","wrong":"import { useSectionSettings } from 'vite-plugin-react-shopify'","symbol":"useSectionSettings","correct":"import { useSectionSettings } from 'vite-plugin-react-shopify/runtime'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport vitePluginShopify from 'vite-plugin-react-shopify';\n\nexport default defineConfig({\n  plugins: [\n    vitePluginShopify({\n      sourceCodeDir: 'frontend',\n    }),\n  ],\n});\n\n// frontend/sections/HelloWorld.tsx\nimport type { ShopifyMeta } from 'vite-plugin-react-shopify';\nimport { useSectionSettings } from 'vite-plugin-react-shopify/runtime';\n\nexport const shopifyMeta = {\n  name: 'Hello World',\n  settings: [\n    { type: 'text', id: 'title', label: 'Title', default: 'Hello, World!' },\n  ],\n  presets: [{ name: 'Hello World' }],\n} satisfies ShopifyMeta;\n\nexport default function HelloWorld() {\n  const { value: title } = useSectionSettings('title');\n  return <h1>{title}</h1>;\n}\n\n// Run: pnpm dev (starts Vite build watch)","lang":"typescript","description":"Configures Vite plugin and defines a Shopify section component with settings."},"warnings":[{"fix":"Upgrade Vite to ^8.0.0 or stick with v1.x of the plugin.","message":"Version 2.x requires Vite 8. Using with Vite 5 or 7 will cause plugin initialization failure.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Change imports: import { useSectionSettings } from 'vite-plugin-react-shopify/runtime'","message":"Runtime hooks moved from main entry to subpath 'vite-plugin-react-shopify/runtime' in v2. Direct imports from 'vite-plugin-react-shopify' will be undefined.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use ssg: { prefix: { section: 'r-', ... } }","message":"The 'prefix' option in ssg config is deprecated. Use 'ssg.prefix' object keys instead of string.","severity":"deprecated","affected_versions":">=2.2.0"},{"fix":"Place shared components in frontend/components/ and import them with relative paths like './components/SharedCard'.","message":"CSS 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure a custom prefix in ssg.prefix to avoid name collisions.","message":"File naming: Generated Liquid files use 'react-' prefix by default. If your theme already has files with that prefix, they may conflict or be overwritten.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use useEffect or lazy loading for browser-specific logic.","message":"Hydration: Components that rely on browser-only APIs (window, document) will fail during SSG build. Wrap them in useEffect or dynamic import.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1':61 '2':75 '2.2.9':54 '3':86 '8.0.0':57 'activ':98 'ai':63 'ai-friend':62 'architectur':97 'base':96 'better':72 'block':22 'build':12,31 'cadenc':105 'compat':51 'compil':19 'compon':17,78,95 'component-bas':94 'current':52 'develop':10,46,65 'differenti':60 'enabl':9 'experi':47 'file':29 'friend':64 'full':44 'generat':37 'github':101 'handl':40 'hydrat':41 'javascript':106 'jest/vitest':85 'key':59 'leverag':67 'liquid':28,74 'llms':70 'maintain':49,99 'modern':87 'plugin':2,7 'provid':42 'react':3,16,20,45,77 'react/typescript':68 'releas':104 'requir':55 'runtim':39 'section':21 'shake':92 'shopifi':4,13,27,50 'site':36 'snippet':23 'ssg':34 'static':35 'templat':25 'test':83 'testabl':76 'theme':14 'three':58 'time':32 'tool':88 'tree':91 'tree-shak':90 'typescript':89,107 'understand':71 'unit':82 'unit-test':81 'use':15 'version':53 'via':33 'vite':1,6,56 'week':103","created_at":"2026-06-04T18:56:19.573321+00:00","updated_at":"2026-06-04T18:56:19.573321+00:00","problems":[{"fix":"Upgrade to v2.2.9: pnpm add vite-plugin-react-shopify@latest","cause":"Using an older version (<2.0.0) that didn't have the runtime subpath.","error":"Cannot find module 'vite-plugin-react-shopify/runtime' or its corresponding type declarations."},{"fix":"Upgrade Vite to ^8.0.0: pnpm add vite@^8.0.0","cause":"Plugin v2 requires Vite 8 as peer dependency.","error":"Error: [vite-plugin-react-shopify] Vite version 7.x is not supported. Please upgrade to Vite 8."},{"fix":"Change to ES module import: import vitePluginShopify from 'vite-plugin-react-shopify'","cause":"Using CommonJS require to import the ESM-only module.","error":"TypeError: plugin is not a function"},{"fix":"Install react and react-dom: pnpm add react react-dom","cause":"Missing peer dependency react or react-dom.","error":"Module not found: Error: Can't resolve 'react' in '/path/to/frontend'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"vite-plugin-react-shopify","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ecommerce","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}