vite-plugin-react-shopify 2.2.3 → 2.2.6

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 import { Plugin } from 'vite';
 
+/**
+ * @file User-facing configuration options for the Vite plugin.
+ *
+ * All fields are optional with sensible defaults applied at resolution time
+ * by {@link resolveOptions} (core/options.ts).
+ */
+/** Top-level plugin options passed to `vitePluginShopify()`. */
 interface Options {
     themeRoot?: string;
     sourceCodeDir?: string;
@@ -9,6 +16,7 @@ interface Options {
     ssg?: SSGOptions;
     importMap?: ImportMapOptions;
 }
+/** Static Site Generation configuration. */
 interface SSGOptions {
     directories?: string[];
     prefix?: {
@@ -20,11 +28,20 @@ interface SSGOptions {
     outputName?: string;
     cssPrefix?: string;
 }
+/** CDN URLs for the import map snippet injected into the theme. */
 interface ImportMapOptions {
     react?: string;
     reactDomClient?: string;
 }
 
+/**
+ * @file TypeScript type definitions for Shopify theme setting schemas.
+ *
+ * Covers every Shopify setting type (text, checkbox, color, image_picker,
+ * etc.) as well as informational sidebar types (header, paragraph). Also
+ * includes utility types for type-level validation ({@link AssertNoEmptyDefaults})
+ * and schema inference ({@link InferSettings}).
+ */
 interface BaseSettingSchema {
     id: string;
     label: string;
@@ -238,39 +255,126 @@ type InferSettings<T extends readonly {
     [K in T[number] as K["id"]]: ValueForType<K["type"]>;
 };
 
+/**
+ * @file Shopify block/section metadata types.
+ *
+ * Defines {@link ShopifyMeta} — the shape of the `shopifyMeta` export from
+ * React components — along with supporting types for presets and block
+ * definitions. This metadata drives schema generation and Liquid output.
+ */
+
+/** The four Shopify theme component categories. */
 type ShopifyBlockType = "template" | "section" | "block" | "snippet";
+/**
+ * A block definition within a section's `blocks` attribute.
+ *
+ * Per the Shopify section schema, each block entry supports the following:
+ *
+ * | Attribute  | Required | Description                                                          |
+ * | ---------- | -------- | -------------------------------------------------------------------- |
+ * | `type`     | Yes      | Free-form block type identifier.                                    |
+ * | `name`     | No       | Block name shown as the block title in the theme editor. Auto-derived from `type` (e.g. `text-block` → `Text Block`) if omitted. |
+ * | `limit`    | No       | Max number of blocks of this type that can be used.                 |
+ * | `settings` | No       | Input or sidebar settings exposed to the merchant for this block.    |
+ */
+interface BlockDefinition {
+    type: string;
+    name?: string;
+    limit?: number;
+    settings?: SettingSchema[];
+}
+/**
+ * Template/group scope filter used by `enabled_on` / `disabled_on`.
+ *
+ * Per the Shopify section schema, at least one of `templates` or `groups`
+ * must be provided. `enabled_on` and `disabled_on` are mutually exclusive —
+ * a section may declare one but not both.
+ *
+ * | Attribute   | Description                                                                              |
+ * | ----------- | ---------------------------------------------------------------------------------------- |
+ * | `templates` | Page types the section is restricted to (or excluded from). Use `["*"]` for all.        |
+ * | `groups`    | Section group types: `header`, `footer`, `aside`, or `custom.<NAME>`. Use `["*"]` for all. |
+ */
+interface TemplateScope {
+    templates?: string[];
+    groups?: string[];
+}
+/**
+ * Section-level translation overrides for the schema.
+ *
+ * Each entry maps a language code (e.g. `"en"`, `"fr"`) to a flat key/value
+ * translation map. When emitted, translations are accessed in Liquid via
+ * the `t` filter using the key `sections.<section-name>.<key>`.
+ */
+type SectionLocales = Record<string, Record<string, string>>;
+/**
+ * Metadata for a Shopify section, block, snippet, or template.
+ *
+ * Exported as `shopifyMeta` from the React component file. Drives the
+ * generated {% schema %} block and influences Liquid wrapper output.
+ */
 interface ShopifyMeta {
     type?: ShopifyBlockType;
     name?: string;
-    tag?: string;
+    /**
+     * HTML wrapper tag. Use `null` to render without a wrapper (blocks only).
+     *
+     * For sections Shopify only accepts a fixed set of tags (`article`,
+     * `aside`, `div`, `footer`, `header`, `section`); for blocks any string
+     * up to 50 chars is accepted.
+     */
+    tag?: string | null;
     class?: string;
     limit?: number;
     params?: string[];
     settings?: SettingSchema[];
-    blocks?: {
-        type: string;
-        name?: string;
-        settings?: SettingSchema[];
-    }[];
+    blocks?: BlockDefinition[];
     max_blocks?: number;
     presets?: PresetDefinition[];
-    enabled_on?: Record<string, string>[];
-    disabled_on?: Record<string, string>[];
-    templates?: string[];
-}
+    /**
+     * Default configuration used when a section is statically rendered. Has
+     * the same shape as a {@link PresetDefinition}.
+     */
+    default?: PresetDefinition;
+    /**
+     * Inline translation overrides for the section, scoped to the
+     * theme editor's **Sections** tab.
+     */
+    locales?: SectionLocales;
+    enabled_on?: TemplateScope;
+    disabled_on?: TemplateScope;
+}
+/** A theme editor preset definition within the schema. */
 interface PresetDefinition {
     name: string;
     category?: string;
     settings?: InputSettings;
     blocks?: PresetBlock[];
 }
-interface PresetBlock {
+interface CommonBlockPreset {
     type: string;
-    id?: string;
-    static?: boolean;
+    name?: string;
     settings?: InputSettings;
     blocks?: PresetBlock[];
 }
+interface ShopifyNormalBlockPreset extends CommonBlockPreset {
+    id?: never;
+    static?: never;
+}
+interface ShopifyStaticBlockPreset extends CommonBlockPreset {
+    id: string;
+    static: true;
+}
+/** A nested block preset inside a parent preset. */
+type PresetBlock = ShopifyNormalBlockPreset | ShopifyStaticBlockPreset;
+
+/**
+ * @file SSG entry type representing a discovered React component target.
+ *
+ * Each entry maps to one Liquid output file (section, block, snippet, or
+ * template). The {@link SSGEntry.meta} field carries {@link ShopifyMeta}
+ * merged with auto-derived defaults.
+ */
 
 interface SSGEntry {
     filePath: string;
@@ -280,6 +384,29 @@ interface SSGEntry {
     meta: Required<Pick<ShopifyMeta, "name">> & ShopifyMeta;
 }
 
+/**
+ * @file Main entry point for the `vite-plugin-react-shopify` package.
+ *
+ * Composes four Vite plugins (hydration-fix, config, entries, SSG) into
+ * a single array returned to the user's `vite.config.ts`. Also re-exports
+ * all public types for consumers.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import vitePluginShopify from 'vite-plugin-react-shopify'
+ * export default {
+ *   plugins: [vitePluginShopify({ themeRoot: '.', sourceCodeDir: 'frontend' })],
+ * }
+ * ```
+ */
+
+/**
+ * Create the complete set of Vite plugins for React Shopify theme development.
+ *
+ * @param options User configuration (all fields optional).
+ * @returns An array of Vite plugin instances.
+ */
 declare const vitePluginShopify: (options?: Options) => Plugin[];
 
-export { type ArticleListSetting, type ArticleSetting, type AssertNoEmptyDefaults, type BlogSetting, type CheckboxSetting, type CollectionListSetting, type CollectionSetting, type ColorBackgroundSetting, type ColorSchemeGroupSetting, type ColorSchemeRole, type ColorSchemeSetting, type ColorSetting, type FontPickerSetting, type HeaderSetting, type HtmlSetting, type ImagePickerSetting, type ImportMapOptions, type InferSettings, type InlineRichtextSetting, type InputSettingSchema, type InputSettings, type LineBreakSetting, type LinkListSetting, type LiquidSetting, type MetaobjectListSetting, type MetaobjectSetting, type NumberSetting, type Options, type PageSetting, type ParagraphSetting, type PresetBlock, type PresetDefinition, type ProductListSetting, type ProductSetting, type RadioSetting, type RangeSetting, type RichtextSetting, type SSGEntry, type SSGOptions, type SchemaSetting, type SelectSetting, type SettingSchema, type SettingType, type SettingValue, type ShopifyBlockType, type ShopifyMeta, type SidebarSetting, type TextAlignmentSetting, type TextSetting, type TextareaSetting, type UrlSetting, type VideoSetting, type VideoUrlSetting, vitePluginShopify as default };
+export { type ArticleListSetting, type ArticleSetting, type AssertNoEmptyDefaults, type BlockDefinition, type BlogSetting, type CheckboxSetting, type CollectionListSetting, type CollectionSetting, type ColorBackgroundSetting, type ColorSchemeGroupSetting, type ColorSchemeRole, type ColorSchemeSetting, type ColorSetting, type FontPickerSetting, type HeaderSetting, type HtmlSetting, type ImagePickerSetting, type ImportMapOptions, type InferSettings, type InlineRichtextSetting, type InputSettingSchema, type InputSettings, type LineBreakSetting, type LinkListSetting, type LiquidSetting, type MetaobjectListSetting, type MetaobjectSetting, type NumberSetting, type Options, type PageSetting, type ParagraphSetting, type PresetBlock, type PresetDefinition, type ProductListSetting, type ProductSetting, type RadioSetting, type RangeSetting, type RichtextSetting, type SSGEntry, type SSGOptions, type SchemaSetting, type SectionLocales, type SelectSetting, type SettingSchema, type SettingType, type SettingValue, type ShopifyBlockType, type ShopifyMeta, type SidebarSetting, type TemplateScope, type TextAlignmentSetting, type TextSetting, type TextareaSetting, type UrlSetting, type VideoSetting, type VideoUrlSetting, vitePluginShopify as default };

package/dist/index.js

@@ -154,6 +154,24 @@ import { normalizePath as normalizePath2 } from "vite";
 import path3 from "path";
 import glob from "fast-glob";
 import { normalizePath } from "vite";
+
+// src/validate/rules.ts
+var MAX_NAME_LENGTH = 25;
+function checkNameLength(meta, kebabName) {
+  if (meta.name.length > MAX_NAME_LENGTH) {
+    return `[${kebabName}] shopifyMeta.name "${meta.name}" is ${meta.name.length} chars (Shopify limit: ${MAX_NAME_LENGTH})`;
+  }
+  return null;
+}
+function checkEmptyStringDefault(setting) {
+  if (setting.default === "") {
+    const label = "id" in setting && setting.id ? setting.id : "(no id)";
+    return `Setting "${label}" (type: ${setting.type}) has empty string default`;
+  }
+  return null;
+}
+
+// src/ssg/scanner.ts
 var TYPE_BY_DIR = {
   templates: "template",
   sections: "section",
@@ -188,7 +206,7 @@ function toKebabCase(str) {
 }
 function deriveName(fileName) {
   const readable = fileName.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[-_]/g, " ").replace(/\s+/g, " ").trim();
-  return readable.length > 25 ? readable.slice(0, 25) : readable;
+  return readable.length > MAX_NAME_LENGTH ? readable.slice(0, MAX_NAME_LENGTH) : readable;
 }
 
 // src/core/entry-template.ts
@@ -295,98 +313,73 @@ import path9 from "path";
 // src/ssg/css-manager.ts
 import fs from "fs";
 import path5 from "path";
-var log3 = logger("ssg:css");
-function collectCssFiles(manifestKey, manifest) {
-  const collected = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  collectCssFilesRecursive(manifestKey, manifest, collected, visited);
-  return [...collected];
-}
-function collectCssFilesRecursive(chunkKey, manifest, collected, visited) {
-  if (visited.has(chunkKey)) return;
-  visited.add(chunkKey);
-  const chunk = manifest[chunkKey];
-  if (!chunk) return;
-  if (chunk.css && Array.isArray(chunk.css)) {
-    for (const cssFile of chunk.css) {
-      collected.add(cssFile);
-    }
-  }
-  if (chunk.imports && Array.isArray(chunk.imports)) {
-    for (const imported of chunk.imports) {
-      collectCssFilesRecursive(imported, manifest, collected, visited);
-    }
-  }
-}
-function readCssFileContents(cssFiles, buildDir, themeRoot) {
-  const assetsDir = path5.resolve(themeRoot, buildDir);
-  return cssFiles.map((file) => {
-    try {
-      return fs.readFileSync(path5.join(assetsDir, file), "utf-8");
-    } catch {
-      return "";
-    }
-  }).filter(Boolean);
-}
-function getCssBaseName(cssFile) {
-  const name = cssFile.replace(/\.css$/, "");
-  const lastHyphen = name.lastIndexOf("-");
-  if (lastHyphen > 0) {
-    const possibleHash = name.slice(lastHyphen + 1);
-    if (/^[A-Za-z0-9_-]{8,}$/.test(possibleHash)) {
-      return name.slice(0, lastHyphen);
-    }
-  }
-  return name;
-}
 function analyzeCssDistribution(entries, manifest) {
   const entryCssFiles = /* @__PURE__ */ new Map();
   const cssRefCount = /* @__PURE__ */ new Map();
   for (const entry of entries) {
     const manifestKey = `shopify:entry:${entry.kebabName}`;
-    const files = collectCssFiles(manifestKey, manifest);
-    entryCssFiles.set(entry.kebabName, files);
-    for (const f of files) {
+    const chunk = manifest[manifestKey];
+    if (!chunk) continue;
+    const cssFiles = collectCssFiles(chunk, manifest, /* @__PURE__ */ new Set());
+    entryCssFiles.set(entry.kebabName, cssFiles);
+    for (const f of cssFiles) {
       cssRefCount.set(f, (cssRefCount.get(f) || 0) + 1);
     }
-    log3.debug("entry %s has %d CSS files", entry.kebabName, files.length);
   }
   return { entryCssFiles, cssRefCount };
 }
 function generateSharedCssSnippets(cssRefCount, options) {
   const cssSnippetMap = /* @__PURE__ */ new Map();
+  const snippetsDir = path5.resolve(options.themeRoot, "snippets");
+  fs.mkdirSync(snippetsDir, { recursive: true });
   for (const [cssFile, count] of cssRefCount) {
-    if (count > 1) {
-      const snippetName = `${options.ssg.cssPrefix}-${getCssBaseName(cssFile)}`;
-      cssSnippetMap.set(cssFile, snippetName);
-      const snippetPath = path5.join(
-        path5.resolve(options.themeRoot),
-        "snippets",
-        `${snippetName}.liquid`
-      );
-      const cssPath = path5.join(
-        path5.resolve(options.themeRoot, options.buildDir),
-        cssFile
-      );
-      try {
-        const cssContent = fs.readFileSync(cssPath, "utf-8");
-        fs.mkdirSync(path5.dirname(snippetPath), { recursive: true });
-        fs.writeFileSync(snippetPath, `{% stylesheet %}
-${cssContent.trim()}
+    if (count < 2) continue;
+    const cssName = path5.basename(cssFile, path5.extname(cssFile));
+    const snippetName = `${options.ssg.cssPrefix || "css-"}${cssName}`;
+    const cssContent = readCssFile(cssFile, options.buildDir, options.themeRoot);
+    fs.writeFileSync(
+      path5.join(snippetsDir, `${snippetName}.liquid`),
+      `{% stylesheet %}
+${cssContent}
 {% endstylesheet %}
-`);
-        log3.debug("generated shared CSS snippet %s (used by %d entries)", snippetName, count);
-      } catch {
-        log3.warn("failed to write CSS snippet for %s", cssFile);
-      }
-    }
+`
+    );
+    cssSnippetMap.set(cssFile, snippetName);
   }
   return cssSnippetMap;
 }
 function categorizeCss(cssFiles, cssSnippetMap) {
-  const snippets = cssFiles.filter((f) => cssSnippetMap.has(f)).map((f) => cssSnippetMap.get(f));
-  const inlineFiles = cssFiles.filter((f) => !cssSnippetMap.has(f));
-  return { inline: inlineFiles, snippets };
+  const inline = [];
+  const snippets = [];
+  for (const f of cssFiles) {
+    const snippetName = cssSnippetMap.get(f);
+    if (snippetName) {
+      snippets.push(snippetName);
+    } else {
+      inline.push(f);
+    }
+  }
+  return { inline, snippets };
+}
+function readCssFileContents(cssFiles, buildDir, themeRoot) {
+  return cssFiles.map((f) => readCssFile(f, buildDir, themeRoot));
+}
+function readCssFile(cssFile, buildDir, themeRoot) {
+  return fs.readFileSync(path5.resolve(themeRoot, buildDir, cssFile), "utf-8");
+}
+function collectCssFiles(chunk, manifest, visited) {
+  if (visited.has(chunk.file)) return [];
+  visited.add(chunk.file);
+  const css = [...chunk.css || []];
+  if (chunk.imports) {
+    for (const imp of chunk.imports) {
+      const child = manifest[imp];
+      if (child) {
+        css.push(...collectCssFiles(child, manifest, visited));
+      }
+    }
+  }
+  return css;
 }
 
 // src/ssg/bundler.ts
@@ -397,11 +390,11 @@ import { createRequire } from "module";
 // src/hydration-fix/index.ts
 import { parseSync } from "oxc-parser";
 import { walk } from "oxc-walker";
-var log4 = logger("hydration-fix");
+var log3 = logger("hydration-fix");
 function autoFixAdjacentText(source, filePath) {
   const parseResult = parseSync(filePath, source);
   if (parseResult.errors.length > 0) {
-    log4.debug("OXC parse errors for %s, skipping hydration fix", filePath);
+    log3.debug("OXC parse errors for %s, skipping hydration fix", filePath);
     return { result: source, fixCount: 0 };
   }
   const replacements = [];
@@ -423,7 +416,7 @@ function autoFixAdjacentText(source, filePath) {
   for (const { start, end, replacement } of replacements) {
     fixed = fixed.slice(0, start) + replacement + fixed.slice(end);
   }
-  log4.warn(
+  log3.warn(
     `auto-fixed ${replacements.length} adjacent text+expression issue(s) in ${filePath}`
   );
   return { result: fixed, fixCount: replacements.length };
@@ -478,14 +471,14 @@ function needsFix(content) {
 }
 
 // src/ssg/bundler.ts
-var log5 = logger("ssg:bundler");
+var log4 = logger("ssg:bundler");
 async function bundleEntry(entry, projectRoot, sourceDir) {
   const projectRequire = createRequire(path6.join(projectRoot, "package.json"));
   let esbuild;
   try {
     esbuild = projectRequire("esbuild");
   } catch {
-    log5.warn("esbuild not found, skipping SSR for %s", entry.kebabName);
+    log4.warn("esbuild not found, skipping SSR for %s", entry.kebabName);
     return null;
   }
   const sourceCode = fs2.readFileSync(entry.filePath, "utf-8");
@@ -495,7 +488,7 @@ async function bundleEntry(entry, projectRoot, sourceDir) {
   const tmpDir = path6.join(sourceDir, ".ssg-tmp");
   fs2.mkdirSync(tmpDir, { recursive: true });
   const tmpFile = path6.join(tmpDir, `.ssg-entry-${ts}.mjs`);
-  log5.debug("bundling %s via esbuild", entry.kebabName);
+  log4.debug("bundling %s via esbuild", entry.kebabName);
   const startBundled = Date.now();
   await esbuild.build({
     stdin: {
@@ -519,6 +512,7 @@ async function bundleEntry(entry, projectRoot, sourceDir) {
     allowOverwrite: true,
     plugins: [
       {
+        // Re-apply hydration fix to all TSX/JSX files loaded during bundle
         name: "ssg-hydration-fix",
         setup(build) {
           build.onLoad({ filter: /\.(tsx|jsx)$/ }, (args) => {
@@ -529,13 +523,14 @@ async function bundleEntry(entry, projectRoot, sourceDir) {
                 return { contents: result, loader: args.path.endsWith(".tsx") ? "tsx" : "jsx" };
               }
             } catch (e) {
-              log5.debug("SSG hydration-fix failed for %s: %s", args.path, e);
+              log4.debug("SSG hydration-fix failed for %s: %s", args.path, e);
             }
             return void 0;
           });
         }
       },
       {
+        // Strip CSS imports — not needed for SSR, replaced by Liquid stylesheet
         name: "ssg-strip-css",
         setup(build) {
           build.onResolve({ filter: /\.module\.css$/ }, (args) => ({
@@ -558,7 +553,7 @@ async function bundleEntry(entry, projectRoot, sourceDir) {
       }
     ]
   });
-  log5.debug("esbuild bundle took %dms", Date.now() - startBundled);
+  log4.debug("esbuild bundle took %dms", Date.now() - startBundled);
   return { tmpFile };
 }
 
@@ -589,7 +584,7 @@ function pathToFileURL(filePath) {
   }
   return "file://" + absPath;
 }
-var log6 = logger("ssg:renderer");
+var log5 = logger("ssg:renderer");
 var DEFAULT_LIQUID_FILTERS = {
   textarea: " | newline_to_br",
   image_picker: " | img_url: 'master'"
@@ -610,7 +605,7 @@ function renderEntry(tmpFile, entry, projectRoot) {
     const Component = mod.default;
     const shopifyMeta = mod.shopifyMeta;
     if (!Component) {
-      log6.warn("No default export found in %s, skipping", entry.filePath);
+      log5.warn("No default export found in %s, skipping", entry.filePath);
       return null;
     }
     if (shopifyMeta) {
@@ -623,7 +618,7 @@ function renderEntry(tmpFile, entry, projectRoot) {
       createElement = projectRequire("react").createElement;
       renderToStaticMarkup = projectRequire("react-dom/server").renderToStaticMarkup;
     } catch {
-      log6.warn("react/react-dom not found, skipping SSR for %s", entry.kebabName);
+      log5.warn("react/react-dom not found, skipping SSR for %s", entry.kebabName);
       return null;
     }
     globalThis.__shopify_ssg_target = entry.targetType;
@@ -655,71 +650,76 @@ function resolveScriptAsset(kebabName, manifest) {
 }
 
 // src/ssg/schema.ts
-function serializeSetting(setting) {
-  const s = { type: setting.type };
-  if ("id" in setting) s.id = setting.id;
-  if ("label" in setting) s.label = setting.label;
-  if ("default" in setting && setting.default !== void 0) {
-    s.default = setting.default;
-  }
-  if ("info" in setting && setting.info) s.info = setting.info;
-  if ("placeholder" in setting && setting.placeholder) {
-    s.placeholder = setting.placeholder;
-  }
-  if ("options" in setting && setting.options) s.options = setting.options;
-  if ("min" in setting && setting.min !== void 0) s.min = setting.min;
-  if ("max" in setting && setting.max !== void 0) s.max = setting.max;
-  if ("step" in setting && setting.step !== void 0) s.step = setting.step;
-  if ("unit" in setting && setting.unit) s.unit = setting.unit;
-  if ("accept" in setting && setting.accept) s.accept = setting.accept;
-  if ("metaobject_type" in setting && setting.metaobject_type) {
-    s.metaobject_type = setting.metaobject_type;
-  }
-  if ("limit" in setting && setting.limit !== void 0) s.limit = setting.limit;
-  if ("content" in setting && setting.content) s.content = setting.content;
-  if ("definition" in setting && setting.definition) {
-    s.definition = setting.definition.map(serializeSetting);
-  }
-  if ("role" in setting && setting.role) s.role = setting.role;
-  return s;
-}
 function generateSchema(meta) {
-  const schema = {
-    name: meta.name
-  };
-  if (meta.tag) schema.tag = meta.tag;
-  if (meta.class) schema.class = meta.class;
-  if (meta.limit !== void 0) schema.limit = meta.limit;
-  if (meta.max_blocks !== void 0) schema.max_blocks = meta.max_blocks;
-  if (meta.settings && meta.settings.length > 0) {
-    schema.settings = meta.settings.map(serializeSetting);
-  }
-  if (meta.blocks && meta.blocks.length > 0) {
-    schema.blocks = meta.blocks.map((block) => {
-      const b = { type: block.type };
-      if (block.name) b.name = block.name;
-      if (block.settings) b.settings = block.settings;
-      return b;
-    });
-  }
-  if (meta.presets && meta.presets.length > 0) {
-    schema.presets = meta.presets.map((preset) => {
-      const p = { name: preset.name };
-      if (preset.category) p.category = preset.category;
-      if (preset.settings) p.settings = preset.settings;
-      if (preset.blocks) p.blocks = preset.blocks;
-      return p;
-    });
-  }
-  if (meta.enabled_on) schema.enabled_on = meta.enabled_on;
-  if (meta.disabled_on) schema.disabled_on = meta.disabled_on;
-  if (meta.templates) schema.templates = meta.templates;
+  const schema = buildSchema(meta);
   const json = JSON.stringify(schema, null, 2);
   return `
 {% schema %}
 ${json}
-{% endschema %}
-`;
+{% endschema %}`;
+}
+function buildSchema(meta) {
+  return {
+    name: meta.name ?? "",
+    ...meta.tag !== void 0 ? { tag: meta.tag } : {},
+    class: meta.class ?? "",
+    limit: meta.limit,
+    ...meta.max_blocks != null ? { max_blocks: meta.max_blocks } : {},
+    settings: meta.settings || [],
+    blocks: meta.blocks ? meta.blocks.map((b) => serializeBlockDefinition(b)) : void 0,
+    presets: meta.presets ? meta.presets.map((p) => serializePreset(p)) : void 0,
+    ...meta.default ? { default: serializePreset(meta.default) } : {},
+    ...meta.locales ? { locales: meta.locales } : {},
+    ...meta.enabled_on ? { enabled_on: meta.enabled_on } : {},
+    ...meta.disabled_on ? { disabled_on: meta.disabled_on } : {}
+  };
+}
+function defaultBlockName(type) {
+  const name = type.replace(/^@/, "").split(/[-_\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  return name.length > MAX_NAME_LENGTH ? name.slice(0, MAX_NAME_LENGTH) : name;
+}
+function serializeBlockDefinition(block) {
+  const { type, name, limit, settings } = block;
+  return {
+    type,
+    name: name ?? defaultBlockName(type),
+    ...limit != null ? { limit } : {},
+    ...settings ? { settings } : {}
+  };
+}
+function serializeInputSettings(settings) {
+  if (!settings) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(settings)) {
+    out[key] = value === "" ? void 0 : value;
+  }
+  return out;
+}
+function serializePresetBlock(block) {
+  const p = { type: block.type };
+  if (block.name) p.name = block.name;
+  if (block.static) {
+    p.static = true;
+    if (block.id) p.id = block.id;
+  }
+  const settings = serializeInputSettings(
+    "settings" in block ? block.settings : void 0
+  );
+  if (settings) p.settings = settings;
+  if (!block.static && block.blocks?.length) {
+    p.blocks = block.blocks.map(serializePresetBlock);
+  }
+  return p;
+}
+function serializePreset(preset) {
+  const obj = { name: preset.name };
+  if (preset.category) obj.category = preset.category;
+  const settings = serializeInputSettings(preset.settings);
+  if (settings) obj.settings = settings;
+  if (preset.blocks?.length) {
+    obj.blocks = preset.blocks.map(serializePresetBlock);
+  }
+  return obj;
 }
 
 // src/ssg/liquid-paths.ts
@@ -878,24 +878,8 @@ function buildSnippet(html, entry, trackedExpressions, liquidPrepend = "") {
   return lines;
 }
 
-// src/validate/rules.ts
-var MAX_NAME_LENGTH = 25;
-function checkNameLength(meta, kebabName) {
-  if (meta.name.length > MAX_NAME_LENGTH) {
-    return `[${kebabName}] shopifyMeta.name "${meta.name}" is ${meta.name.length} chars (Shopify limit: ${MAX_NAME_LENGTH})`;
-  }
-  return null;
-}
-function checkEmptyStringDefault(setting) {
-  if (setting.default === "") {
-    const label = "id" in setting && setting.id ? setting.id : "(no id)";
-    return `Setting "${label}" (type: ${setting.type}) has empty string default`;
-  }
-  return null;
-}
-
 // src/validate/index.ts
-var log7 = logger("validate");
+var log6 = logger("validate");
 function validateShopifyMeta(meta, context) {
   const warnings = [];
   const nameWarning = checkNameLength(meta, context.kebabName);
@@ -910,17 +894,17 @@ function validateShopifyMeta(meta, context) {
     }
   }
   for (const w of warnings) {
-    log7.warn(w);
+    log6.warn(w);
   }
   return warnings;
 }
 
 // src/ssg/compiler.ts
-var log8 = logger("ssg:compiler");
+var log7 = logger("ssg:compiler");
 async function compileAllEntries(options, manifest) {
   const entries = scanEntries(options);
   if (entries.length === 0) return;
-  log8.debug("found %d entries to compile", entries.length);
+  log7.debug("found %d entries to compile", entries.length);
   const projectRoot = path9.resolve(options.themeRoot);
   const sourceDir = path9.resolve(options.themeRoot, options.sourceCodeDir);
   const { entryCssFiles, cssRefCount } = analyzeCssDistribution(entries, manifest);
@@ -929,10 +913,10 @@ async function compileAllEntries(options, manifest) {
     try {
       await compileEntry(entry, options, manifest, projectRoot, sourceDir, entryCssFiles, cssSnippetMap);
     } catch (err) {
-      log8.error("Failed to compile %s:", entry.filePath, err);
+      log7.error("Failed to compile %s:", entry.filePath, err);
     }
   }
-  log8.info("Compiled %d entries", entries.length);
+  log7.info("Compiled %d entries", entries.length);
   const tmpDir = path9.join(sourceDir, ".ssg-tmp");
   try {
     fs3.rmSync(tmpDir, { recursive: true, force: true });
@@ -950,7 +934,7 @@ async function compileEntry(entry, options, manifest, projectRoot, sourceDir, en
     const cssFiles = entryCssFiles.get(entry.kebabName) || [];
     const { inline: cssInlineFiles, snippets: cssSnippets } = categorizeCss(cssFiles, cssSnippetMap);
     const cssInline = readCssFileContents(cssInlineFiles, options.buildDir, options.themeRoot);
-    log8.debug(
+    log7.debug(
       "compiling %s (type=%s, css inline=%d, css snippets=%d)",
       entry.kebabName,
       entry.targetType,
@@ -985,7 +969,7 @@ async function compileEntry(entry, options, manifest, projectRoot, sourceDir, en
 }
 
 // src/ssg/index.ts
-var log9 = logger("ssg");
+var log8 = logger("ssg");
 function shopifySSG(options) {
   return {
     name: "vite-plugin-shopify:ssg",
@@ -1001,16 +985,16 @@ function shopifySSG(options) {
         "manifest.json"
       );
       if (!fs4.existsSync(manifestPath)) {
-        log9.warn("No manifest.json found, skipping SSG");
+        log8.warn("No manifest.json found, skipping SSG");
         return;
       }
-      log9.debug("reading manifest from %s", manifestPath);
+      log8.debug("reading manifest from %s", manifestPath);
       const manifest = JSON.parse(fs4.readFileSync(manifestPath, "utf-8"));
-      log9.info("Starting SSG compilation...");
+      log8.info("Starting SSG compilation...");
       await compileAllEntries(options, manifest);
-      log9.info("SSG compilation complete");
+      log8.info("SSG compilation complete");
       writeImportMapSnippet(options);
-      log9.debug("wrote import map snippet");
+      log8.debug("wrote import map snippet");
     },
     resolveId(id) {
       if (id === "vite-plugin-shopify/runtime") {

package/dist/runtime/index.d.ts

@@ -1,35 +1,104 @@
 import * as react from 'react';
 
+/**
+ * Parses a Liquid value into a boolean following Shopify truthiness rules:
+ * `false`, `""`, `"0"`, `undefined`, and `null` are falsy; everything else is
+ * truthy.
+ */
 declare function parseLiquidBoolean(value: string | boolean | undefined | null): boolean;
+/**
+ * Parses a Liquid value into a number, falling back to `defaultVal` (default 0)
+ * when the value is `undefined`, `null`, or unparseable.
+ */
 declare function parseLiquidNumber(value: string | number | undefined | null, defaultVal?: number): number;
+/** Type mode hint for `useLiquidValue` — controls how the raw string is coerced. */
 type LiquidTypeMode = "string" | "number" | "boolean";
 type Setter<T> = (val: T | ((prev: T) => T)) => void;
 type ValueForMode<M extends LiquidTypeMode | undefined> = M extends "number" ? number : M extends "boolean" ? boolean : string | undefined;
+/**
+ * Reads a single Liquid setting and returns a React state tuple.
+ *
+ * Overloads allow compile-time type narrowing based on the `type` argument:
+ * - No `type` or `"string"` → `[string | undefined, Setter]`
+ * - `"number"` → `[number, Setter]`
+ * - `"boolean"` → `[boolean, Setter]`
+ *
+ * @param expr - Liquid expression to read (e.g. `"section.settings.title"`).
+ * @param type  - Type coercion mode: `"string"` (default), `"number"`, or `"boolean"`.
+ */
 declare function useLiquidValue(expr: string): [string | undefined, Setter<string | undefined>];
 declare function useLiquidValue(expr: string, type: "string"): [string | undefined, Setter<string | undefined>];
 declare function useLiquidValue(expr: string, type: "number"): [number, Setter<number>];
 declare function useLiquidValue(expr: string, type: "boolean"): [boolean, Setter<boolean>];
+/** Maps individual keys in a Liquid expression map to a type mode (string/number/boolean). */
 type TypeModes<T extends Record<string, string>> = Partial<{
     [K in keyof T & string]: LiquidTypeMode;
 }>;
+/** Infers the resolved value types for each key in a Liquid expression map. */
 type InferValues<T extends Record<string, string>, Types extends TypeModes<T>> = {
     [K in keyof T & string]: ValueForMode<Types[K]>;
 };
+/**
+ * Reads multiple Liquid settings simultaneously and returns a single state object.
+ *
+ * Like `useLiquidValue` but batched — takes a name-to-expression mapping and an
+ * optional name-to-type-mode mapping. Returns a plain object with the resolved
+ * (and type-coerced) values.
+ *
+ * @param map   - Object mapping keys to Liquid expression strings.
+ * @param types - Optional per-key type mode overrides (default: `"string"`).
+ */
 declare function useLiquidValues<T extends Record<string, string>, const Types extends TypeModes<T> = {}>(map: T, types?: Types): InferValues<T, Types>;
+/**
+ * Reads a section-level setting value.
+ *
+ * Equivalent to `useLiquidRaw(\`section.settings.${key}\`)`.
+ */
 declare function useSectionSettings(key: string): {
     value: string | undefined;
 };
+/**
+ * Reads a block-level setting value.
+ *
+ * Equivalent to `useLiquidRaw(\`block.settings.${key}\`)`.
+ */
 declare function useBlockSettings(key: string): {
     value: string | undefined;
 };
+/**
+ * Reads a snippet parameter by name.
+ */
 declare function useSnippetParams(key: string): {
     value: string | undefined;
 };
+/**
+ * Reads a block parameter by name.
+ */
 declare function useBlockParams(key: string): {
     value: string | undefined;
 };
+/**
+ * Registers a block of raw Liquid code for injection into the generated
+ * `.liquid` file. During SSR the code (and any `{{ expr }}` references it
+ * contains) is accumulated in global registries; on the client it is a no-op.
+ *
+ * The registered Liquid code is injected **before** the JSON bridge in the
+ * assembled output so that any variables it defines are available for the
+ * bridge's `json` filter.
+ *
+ * @param code - Raw Liquid template code (may include `{{ }}` expressions).
+ * @returns Always returns an empty string — the Liquid code is rendered
+ *   server-side only.
+ */
 declare function useLiquidBlock(code: string): string;
 
+/**
+ * @file React context provider for Liquid data consumed by runtime hooks.
+ *
+ * The `LiquidDataContext` carries server-rendered Liquid values (from the JSON
+ * bridge) down to {@link useLiquidValue} and related hooks during client-side
+ * hydration. Without this provider, hooks return `undefined` on the client.
+ */
 declare const LiquidDataContext: react.Context<Record<string, any>>;
 declare const LiquidDataProvider: react.Provider<Record<string, any>>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-react-shopify",
-  "version": "2.2.3",
+  "version": "2.2.6",
   "description": "Vite plugin for React Shopify themes",
   "files": [
     "dist"
@@ -17,6 +17,16 @@
       "default": "./dist/runtime/index.js"
     }
   },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup && cp dev-server-index.html dist/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "release": "bumpp && pnpm publish",
+    "release:patch": "bumpp --patch",
+    "release:minor": "bumpp --minor",
+    "release:major": "bumpp --major"
+  },
   "dependencies": {
     "debug": "^4.4.0",
     "fast-glob": "^3.3.0",
@@ -34,15 +44,5 @@
   },
   "peerDependencies": {
     "vite": "^8.0.0"
-  },
-  "scripts": {
-    "dev": "tsup --watch",
-    "build": "tsup && cp dev-server-index.html dist/",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "release": "bumpp && pnpm publish",
-    "release:patch": "bumpp --patch",
-    "release:minor": "bumpp --minor",
-    "release:major": "bumpp --major"
   }
-}
+}