shopify-checkout-extensions
Build Checkout UI Extensions to customize Shopify checkout with sandboxed React-like components. Use when replacing checkout.liquid (deprecated Aug 2025), adding custom fields to checkout, displaying banners, or reading checkout state with hooks. Trigger with phrases like "shopify checkout extension", "shopify checkout ui", "checkout customization shopify", "checkout.liquid migration", "shopify checkout components".
- License 许可
- MIT
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- shopify-checkout-extensions
- tags
- [ "saas", "ecommerce", "shopify" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Build Checkout UI Extensions to customize Shopify checkout with sandboxed React-like components. Use when replacing checkout.liquid (deprecated Aug 2025), adding custom fields to checkout, displaying banners, or reading checkout state with hooks. Trigger with phrases like "shopify checkout extension", "shopify checkout ui", "checkout customization shopify", "checkout.liquid migration", "shopify checkout components".
- allowed-tools
- Read, Write, Edit, Bash(npm:*), Grep
- compatible-with
- claude-code
03 SKILL.md 正文
Shopify Checkout UI Extensions
Overview
Checkout UI Extensions replace checkout.liquid (deprecated August 2025) with sandboxed, React-like components at specific checkout targets. They run in isolation with no DOM access and a strict 64KB bundle limit, using Shopify's component library for consistent, accessible UIs.
Prerequisites
- Shopify CLI 3.x+ and a Shopify Partners app
- Node.js 18+,
@shopify/ui-extensions-reactpackage - Development store with checkout extensibility enabled
Instructions
Step 1: Configure the Extension
# extensions/checkout-banner/shopify.extension.toml
api_version = "2025-01"
type = "ui_extension"
[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.checkout.block.render"
[extensions.capabilities]
api_access = true
network_access = false
Step 2: Build with UI Components
import {
reactExtension, Banner, BlockStack, Text, useSettings,
} from "@shopify/ui-extensions-react/checkout";
export default reactExtension("purchase.checkout.block.render", () => <CheckoutBanner />);
function CheckoutBanner() {
const { banner_text } = useSettings();
return (
<BlockStack spacing="tight">
<Banner status="info">{banner_text || "Free shipping over $50!"}</Banner>
</BlockStack>
);
}
Step 3: Read Checkout Data with Hooks
import {
useApplyMetafieldsChange, useTotalAmount, useShippingAddress, TextField,
} from "@shopify/ui-extensions-react/checkout";
function DeliveryNote() {
const applyMetafieldsChange = useApplyMetafieldsChange();
return (
<TextField
label="Delivery instructions"
onChange={(value) => applyMetafieldsChange({
type: "updateMetafield",
namespace: "custom", key: "delivery_note",
valueType: "string", value,
})}
/>
);
}
Step 4: Bundle Size Strategies
shopify app build --verbose # Check output size
# Import only what you use — each component adds ~1-3KB
# Avoid lodash, date-fns, zod — use native JS
# Split into multiple extensions if approaching 64KB
See extension-targets.md for all targets, ui-components.md for components, and bundle-optimization.md for size strategies.
Output
- Checkout UI extension rendering at the configured target point
- Custom data collection via metafield writes from checkout
- Merchant-configurable settings via the extension editor
- Sandboxed execution with no impact on checkout performance
Error Handling
| Error | Cause | Solution |
|---|---|---|
EXTENSION_LOAD_FAILED |
Bundle exceeds 64KB or invalid code | Tree-shake deps; check size with --verbose |
| Sandbox violation | DOM access, fetch, or window usage |
Use only Shopify components and hooks |
CHECKOUT_COMPLETION_BLOCKED |
Extension error with block_progress |
Add try/catch; test all edge cases |
| Target not rendering | Wrong target or not enabled | Verify target in TOML; check admin placement |
Examples
Adding a Custom Field to Checkout
Collect delivery instructions or gift messages by rendering a text input at a specific checkout target and saving the value as a cart metafield.
See Extension Targets for all available targets and placement options.
Building a Reusable Checkout Banner
Create a merchant-configurable promotional banner using Shopify's UI component library with proper accessibility.
See UI Components for available components and their key props.
Optimizing Extension Bundle Size
Your checkout extension is approaching the 64KB limit. Apply tree-shaking, dependency auditing, and extension splitting strategies.
See Bundle Optimization for size measurement and reduction techniques.
Resources
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".