Shopify UI Extensions Handover & Migration Guide

This guide is prepared to facilitate a smooth transfer of the newly implemented Shopify UI Extensions (both the Admin Order Details block and the Customer Account Order Status block) from this development environment to the original developer's production repository.

Since the original app previously used an iframe-only interface, adding native UI extensions introduces modern Shopify CLI workflows. This document details all necessary steps, file checklists, and configuration adjustments required for a successful migration.

1. Comprehensive Checklist of Files to Transfer

The original developer will need the following directories and files. These represent the entire standalone codebase for the new UI extensions:

Core Extension Folders

Admin Order Details Block: fiscal-order-block/
- shopify.extension.toml — Configuration, targeting, capabilities, and settings.
- src/BlockExtension.jsx — Preact React-like logic using custom s-* elements, state management, and GraphQL fetches.
- locales/en.default.json — Default English translations.
- locales/uk.json — Ukrainian translations.
- shopify.d.ts — Typing references for Shopify global object.
- tsconfig.json — TypeScript configuration.
Customer Account Order Status Block: fiscal-checkout-block/
- shopify.extension.toml — TOML configuration specifying metafield preloads and layout targets.
- src/OrderStatusExtension.jsx — Preact React-like implementation matching Customer Account sandbox rules.
- locales/en.default.json — Default English translations.
- locales/uk.json — Ukrainian translations.
- shopify.d.ts — Typing references.
- tsconfig.json — TypeScript configuration.

Root Configurations (for comparison and merging)

package.json — Required dependencies and CLI scripts.
shopify.app.toml — Application config file mapping to Client ID.
.graphqlrc.js — GraphQL schema codegen setup.

2. Dependencies to Merge (`package.json`)

To build and compile these extensions, the original developer must merge the following dependencies and configurations into their root package.json:

{
  "scripts": {
    "shopify": "shopify",
    "build": "shopify app build",
    "dev": "shopify app dev",
    "deploy": "shopify app deploy"
  },
  "dependencies": {
    "@shopify/ui-extensions": "2025.10.x",
    "@preact/signals": "^2.3.x",
    "preact": "^10.29.1"
  },
  "devDependencies": {
    "@shopify/app": "^3.58.2",
    "@shopify/cli": "^3.93.2"
  },
  "workspaces": [
    "extensions/*"
  ]
}

Note

The modern Shopify CLI uses standard monorepo npm/yarn/pnpm workspaces. Ensuring "workspaces": ["extensions/*"] is in the root package.json allows Shopify CLI to resolve internal typescript modules and dependency trees correctly.

3. TOML Configurations & Migration Steps

A. Root Application TOML (`shopify.app.toml`)

In your staging environment, shopify.app.toml lists your developer App settings:

client_id = "397c02127a580bce65182a72583642d6" (Your Dev App Client ID)
handle = "hutko-fiscal-ui-test"

Action for Staging:

You do not need to share your shopify.app.toml with the developer if they already have an existing CLI app configuration. If they do not have a CLI app configuration (since they were iframe-only), they should create a shopify.app.toml and change:

client_id ➔ Set to their Real Production App Client ID (obtained from the Shopify Partners Dashboard under App > Client ID).
name and handle ➔ Set to their real App name and handle.
application_url ➔ Set to their real production App server domain URL.
redirect_urls ➔ Set to their real production OAuth redirect callbacks.

B. Extension Configurations (`shopify.extension.toml`)

Each extension contains a unique uid in its shopify.extension.toml that couples it to a specific extension registration in your dev Shopify partners account.

Staging Order Block UID: dfc94970-d01c-b839-2220-ffd1b6ab1c86ac3cce4a
Staging Checkout Block UID: ca81c72e-43fb-0709-a9a3-373f38c511faf3b68f36

CRITICAL Handover Modification:

Before sending the files, or immediately upon importing, the original developer MUST delete the uid line from both TOML files:

  api_version = "2025-10"
- uid = "ca81c72e-43fb-0709-a9a3-373f38c511faf3b68f36"
  [[extensions]]
  name = "Fiscal Receipt Info"

Important

When the uid line is absent, running npm run deploy on the production app will trigger the Shopify CLI to automatically prompt the developer: "Create a new extension?" or "Link to an existing extension?" The developer will select "Create new" (or link to an existing placeholder in their production dashboard). Shopify CLI will then dynamically register the extension under their production account and automatically write their own production uid back to the TOML files.

4. Architectural Setup for Iframe-Only (Legacy) Apps

If the developer's original app was entirely iframe-based (e.g. running on a raw Node, Ruby on Rails, or PHP server without Shopify CLI integration):

Coexistence: The existing server can continue to serve the iframe dashboard unmodified. The Shopify CLI only serves as a compilation and build tool to bundle the React/Preact code and deploy it to Shopify's CDN (where modern checkout/admin extension code is securely hosted and run by Shopify).
Setup steps:
- The developer should place their legacy project folder in a subfolder or configure the root directory to act as a Shopify CLI project by running:
```
npm install -D @shopify/cli @shopify/app
```
- Put shopify.app.toml in the project root.
- Create an extensions/ directory and place the fiscal-order-block/ and fiscal-checkout-block/ directories inside it.
- Run npx shopify app deploy to bundle and upload both extensions to the Shopify CDN under their production App listing.

5. Summary Checklist of Next Steps for the Original Developer

Place fiscal-order-block and fiscal-checkout-block inside their extensions/ directory.
Delete uid from both extensions/*/shopify.extension.toml.
Add preact, @preact/signals, and @shopify/ui-extensions to their package dependencies.
Set up workspaces: ["extensions/*"] in their root package.json.
Run npm install to load all UI packaging and building nodes.
Authenticate with Shopify Partners CLI:
```
npx shopify login
```
Run the deploy sequence to register and upload the modern pre-compiled blocks directly onto their production listing:
```
npm run deploy
```
Go to their Shopify Partners Dashboard, find their App, click Extensions, and verify that both new UI Extensions are successfully registered. Finally, release the new version to live stores!

8.8 KiB Raw Blame History