first commit
This commit is contained in:
143
handover.md
Normal file
143
handover.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# 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 = "fiscal-proxy-app"`
|
||||
|
||||
#### 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!
|
||||
Reference in New Issue
Block a user