Shopify Checkout ExtensionsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: shopify-checkout-extensions
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
version: 2.7.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- ecommerce
- shopify
compatibility: Designed for Claude Code
---
# 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-react` package
- Development store with checkout extensibility enabled

## Instructions

### Step 1: Configure the Extension

```toml
# 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

```tsx
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

```tsx
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

```bash
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](references/extension-targets.md) for all targets, [ui-components.md](references/ui-components.md) for components, and [bundle-optimization.md](references/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](references/extension-targets.md) 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](references/ui-components.md) 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](references/bundle-optimization.md) for size measurement and reduction techniques.

## Resources

- [Checkout UI Extensions Overview](https://shopify.dev/docs/apps/build/checkout)
- Extension Targets Reference
- [UI Component Library](https://shopify.dev/docs/api/checkout-ui-extensions/latest/components)
- checkout.liquid Migration Guide

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.