shopify_proxy/handover.md

# 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

1. **Admin Order Details Block**: [fiscal-order-block/](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block)
   - [shopify.extension.toml](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/shopify.extension.toml) — *Configuration, targeting, capabilities, and settings.*
   - [src/BlockExtension.jsx](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/src/BlockExtension.jsx) — *Preact React-like logic using custom `s-*` elements, state management, and GraphQL fetches.*
   - [locales/en.default.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/locales/en.default.json) — *Default English translations.*
   - [locales/uk.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/locales/uk.json) — *Ukrainian translations.*
   - [shopify.d.ts](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/shopify.d.ts) — *Typing references for Shopify global object.*
   - [tsconfig.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/tsconfig.json) — *TypeScript configuration.*

2. **Customer Account Order Status Block**: [fiscal-checkout-block/](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block)
   - [shopify.extension.toml](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/shopify.extension.toml) — *TOML configuration specifying metafield preloads and layout targets.*
   - [src/OrderStatusExtension.jsx](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/src/OrderStatusExtension.jsx) — *Preact React-like implementation matching Customer Account sandbox rules.*
   - [locales/en.default.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/locales/en.default.json) — *Default English translations.*
   - [locales/uk.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/locales/uk.json) — *Ukrainian translations.*
   - [shopify.d.ts](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/shopify.d.ts) — *Typing references.*
   - [tsconfig.json](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/tsconfig.json) — *TypeScript configuration.*

### Root Configurations (for comparison and merging)
- [package.json](file:///home/dev/hutko_shopify_proxy/node/package.json) — *Required dependencies and CLI scripts.*
- [shopify.app.toml](file:///home/dev/hutko_shopify_proxy/node/shopify.app.toml) — *Application config file mapping to Client ID.*
- [.graphqlrc.js](file:///home/dev/hutko_shopify_proxy/node/.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](file:///home/dev/hutko_shopify_proxy/node/package.json):

```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](file:///home/dev/hutko_shopify_proxy/node/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](file:///home/dev/hutko_shopify_proxy/node/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:
- [fiscal-order-block/shopify.extension.toml](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-order-block/shopify.extension.toml)
- [fiscal-checkout-block/shopify.extension.toml](file:///home/dev/hutko_shopify_proxy/node/extensions/fiscal-checkout-block/shopify.extension.toml)

```diff
  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):

1. **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).
2. **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:
     ```bash
     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

1. Place `fiscal-order-block` and `fiscal-checkout-block` inside their `extensions/` directory.
2. Delete `uid` from both `extensions/*/shopify.extension.toml`.
3. Add `preact`, `@preact/signals`, and `@shopify/ui-extensions` to their package dependencies.
4. Set up `workspaces: ["extensions/*"]` in their root `package.json`.
5. Run `npm install` to load all UI packaging and building nodes.
6. Authenticate with Shopify Partners CLI:
   ```bash
   npx shopify login
   ```
7. Run the deploy sequence to register and upload the modern pre-compiled blocks directly onto their production listing:
   ```bash
   npm run deploy
   ```
8. 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!