Overview

This is unoffical sample code for scratch building Shopify app without CLI automatic cocde generation for learing how it works with simple React and GraphQL knowledge.

Making clear, simple, and fewest code is this purpose that's why it doesn't use the CLI generated code.

Reading Shopify OAuth flow might help you to grab the basic.

For quick start with automatically generated code, go to the official CLI tutorial.

Code structure

--------- Backend process in a server (Node.js) ---------
app.js ... Koa Node.js app for backend for app install endpoints, GraphQL API calls, and DB access, etc. No Shopify libraries or CLI generated code used.

package.json ... app.js used npm libaries and scripts for building and running this app.

views/ ... holds Koa Node.js dynamic rendering htmls. This is a SPA app which uses index.html only generated by Vite build in frontend.
  ./index.html ... Koa top page view rendered by app.js server code (for code running, this needs replaced with Vite built one).
public/ ... holds static files hosted by app.js server code (for code running, this needs replaced with Vite built one).

--------- Frontend UI in a browser (React) ---------
frontend/ ... React code base to be built by Vite for app admin UI. All built code runs at the client = browser as minized JS + CSS.

  ./src/ ... React source code with JSX of Shopify App Bridge + Polaris.
  ./index.html ... replaces views/index.html as a Vite built file which renders the root React compoment.  
  ./public/ ... Static files used by React code.
  
  ./package.json ... React code used npm libraries and scripts for building React code with Vite.
  ./vite.config.js ... Vite congfig file for building React code into real runnable minized JS + CSS on browsers.

--------- Extensions with Shopify CLI generation and deployment (Liquid/React/JavaScript/Wasm, etc.) ---------
extensions/ ... automatically generated directory and code by Shopify CLI `npm run generate extension`.

  ./my-XXXXX-ext ... each extension (Theme App / Shopify Functions / Checkout UI / Post-purchase / Web Pixels /... etc.) source.
    ../shopify.app.toml ... each extension configuration required by CLI commands.

React (JSX, Props, State, Hooks, etc.) and GraphQL (Query, Edges, Union, etc.) are mandatory technologies for manipulating this sample.

For creating React frontend, the following contents might help you.

• App Bridge Actions
• Polaris Compoments by React

For extensions like Admin Link, Theme App Extensinons, Shopify Functtions, and Checkout Extensions, refer to the app extensions page.

How to run

1. Add the following environmental variables locally or in cloud platforms like Render / Heroku / Fly, etc.

SHOPIFY_API_KEY:              YOUR_API_KEY (Copy and paste from your app settings in partner dashboard)
SHOPIFY_API_SECRET:           YOUR_API_SECRET (Copy and paste from your app settings in partner dashboard)
SHOPIFY_API_VERSION:          unstable
SHOPIFY_API_SCOPES:           write_products,write_discounts,write_orders,write_payment_customizations,write_delivery_customizations,write_pixels,read_customer_events,write_customers,write_assigned_fulfillment_orders,write_merchant_managed_fulfillment_orders,write_third_party_fulfillment_orders,write_fulfillments,write_inventory,unauthenticated_write_checkouts,unauthenticated_read_product_listings,unauthenticated_write_customers,unauthenticated_read_selling_plans

SHOPIFY_DB_TYPE:              MONGODB (Default) / POSTGRESQL / MYSQL

// The followings are required if you set SHOPIFY_DB_TYPE 'MONGODB'
SHOPIFY_MONGO_DB_NAME:        YOUR_DB_NAME (any name is OK)
SHOPIFY_MONGO_URL:            mongodb://YOUR_USER:YOUR_PASSWORD@YOUR_DOMAIN:YOUR_PORT/YOUR_DB_NAME

// The followings are required if you set SHOPIFY_DB_TYPE 'POSTGRESQL'
SHOPIFY_POSTGRESQL_URL:       postgres://YOUR_USER:YOUR_PASSWORD@YOUR_DOMAIN(:YOUR_PORT)/YOUR_DB_NAME

// The followings are required if you set SHOPIFY_DB_TYPE 'MYSQL'
SHOPIFY_MYSQL_HOST:           YOUR_DOMAIN
SHOPIFY_MYSQL_USER:           YOUR_USER
SHOPIFY_MYSQL_PASSWORD:       YOUR_PASSWORD
SHOPIFY_MYSQL_DATABASE:       YOUR_DB_NAME

// The followings are required if you use `webhookcommon` endpoint as a manually created webhook target.
SHOPIFY_WEBHOOK_SECRET:       YOUR_TEST_STORE_WEBHOOK_SIGNATURE given by the webhook creation settings

2. Build and run the app server locally or in cloud platforms. All settings are described in package.json (note that the built React code contains SHOPIFY_API_KEY value from its envrionment variable, so if you run it with your own app, you have to run the build command below at least one time).

Build command = npm install && npm run build (= cd frontend && npm install && npm run build && rm -rf ../public/assets && mv dist/assets ../public/assets && mv dist/index.html ../views/index.html  *Replacing Koa intex file with Vite buit code)

Start command = npm run start (= node app.js)

*NOTE THAT this sameple doesn't support `npm run dev` of Shopify CLI

3. If you run locally, you need to tunnel localhost for public URL as follows (otherwise, you should use the command lines above for Render or other cloud platform deploy scripts).

cloudflared tunnel --url localhost:3000 or ./ngrok http 3000

4. Set YOUR_APP_URL (your cloudflared or ngrok or other platform root URL) and YOUR_APP_URL/callback to your app settings in partner dashboard. If you add ?external=true parameter to YOUR_APP_URL, the app UX turns into a service connector which tries to connect Shopify stores with their users. Note that if you disable the app embedded (non embedeed app), App Bridge and its Session Token cannot be used so this app shows the same external page using its own JWT which contains "shop", instead of Session Token. (See this demo)

5. (For PostgreSQL or MySQL users only,) create the following table in your database (in psql or mysql command or other tools).

For PostgreSQL:

CREATE TABLE shops ( _id VARCHAR NOT NULL PRIMARY KEY, data json NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL );

For MySQL:

CREATE TABLE shops ( _id VARCHAR(500) NOT NULL PRIMARY KEY, data JSON NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL );

6. Turn OFF [Development store preview] in app extensions menu.

7. Create shopify.app.toml file in the root directory copied from this page to replace client_id value with your SHOPIFY_API_KEY and add use_legacy_install_flow = true under scopes = ... line (check the details).

8. Execute npm run deploy -- --reset and follow its instruction (choose your partner account, connecting to the exising app, etc.) which registers extensions to your exising app and create /.env file which has extensiton ids used by this sample app (For Shopify Functions deployment using Rust, you need Cargo Wasm package installed first by cargo install cargo-wasi).

9. For updating the extensions, execute npm run deploy (without -- --reset) to apply (upload) your local modified files to the created extensions (-- --reset is used for changing your targeted app only).

How to install

Access to the following endpoit. https://SHOPIFY_SHOP_DOMAIN/admin/oauth/authorize?client_id=YOUR_API_KEY&scope=YOUR_API_SCOPES&redirect_uri=YOUR_APP_URL/callback&state=&grant_options[]=　

Or

you can install to your development stores from the app settings in partner dashboard.

Sample list

All sample are available at Wiki.

Trouble shooting

• Your server needs to render the top page at acceptable speed in the right way. Too slow access, error HTTP codes, or server shutdown causes the error above in live stores (not in development ones). Some cloud plarform like Render, Heroku, etc do the very slow response for the first time in a while with free plans, so you need to swtich to Cloudflare tunnel or ngrok hosting or pay those services for higher performence.

TIPS

• If you want to create other language versions of this app like PHP, Java, Ruby, Python, etc., the best way is creating an extension-only app by not choosing a Remix template in CLI steps to add your server side code manually.
• You can use the endpoint of webhookgdpr for GDPR Webhooks.
• If you fail to get protected customer data in Checkout UI Extension or API Webhook creation even in dev. stores, submit your app first which enable you get them.

Disclaimer

• This code is fully unofficial and NOT guaranteed to pass the public app review for Shopify app store. The official requirements are described here.
• You need to follow Shopi API Licene and Terms of Use even for custom app usage.
• This code is supposed to be used as tutorials mainly for catching up Shopify app dev and does NOT guarantees all security covered like this consideration. If you use this code for your production, all resposibilties are owned by you and you should check the license first.