Shopify App Starter
This is a sample app to help developers bootstrap their Shopify app development.
It leverages the Shopify API Library on the backend to create an embedded app, and Polaris and App Bridge React on the frontend.
This is the repository used when you create a new Node app with the Shopify CLI, but with some personal (opinionated) choices. It uses Supabase as a database and has setup ready for Bugsnag for error tracking and Segment for data tracking.
Note: to implement Bugsnag error tracking and track app events with Segment, simply get the required API keys for Bugsnag and the Segment write key, copy them in the ENV file and you're good to go!
Requirements
- If you don’t have one, create a Shopify partner account.
- If you don’t have one, create a Development store where you can install and test your app.
- Install the Shopify CLI.
Setup
To start, use this repository as template and follow the steps below:
Create a new app
- After creating a copy of this repository in your Github account, clone the repo locally on your machine and run
npm install
. - Create a public app in your Shopify partner account. As App url and allowed redirect urls simply add
https://localhost/
for now.
Database Setup
- Create a Supabase account for your app database.
- Create a new project and once is ready, create the 2 following tables:
sessions table
field | type |
---|---|
id | text (primary key) |
session | json |
shop | text |
shops table
field | type |
---|---|
shop | text (primary key) |
id | int8 |
scopes | text |
isInstalled | bool |
subscription | json |
settings | json |
installedAt | timestampz |
uninstalledAt | timestampz |
shopData | json |
hasPreviouslySubscribed | bool |
Alternative and quicker solution:
Copy this SQL commands:
--
-- Name: sessions; Type: TABLE; Schema: public; Owner: supabase_admin
--
CREATE TABLE public.sessions (
id text NOT NULL,
session json NOT NULL,
shop text
);
ALTER TABLE public.sessions OWNER TO supabase_admin;
--
-- Name: shops; Type: TABLE; Schema: public; Owner: supabase_admin
--
CREATE TABLE public.shops (
id bigint NOT NULL,
shop text NOT NULL,
scopes text NOT NULL,
"isInstalled" boolean NOT NULL,
subscription json,
settings json,
"installedAt" timestamp with time zone DEFAULT now(),
"uninstalledAt" timestamp with time zone DEFAULT now(),
"shopData" json,
"hasPreviouslySubscribed" boolean,
notifications text[],
"showOnboarding" boolean DEFAULT true NOT NULL
);
ALTER TABLE public.shops OWNER TO supabase_admin;
--
-- Name: shops_id_seq; Type: SEQUENCE; Schema: public; Owner: supabase_admin
--
ALTER TABLE public.shops ALTER COLUMN id ADD GENERATED BY DEFAULT AS IDENTITY (
SEQUENCE NAME public.shops_id_seq
START WITH 1
INCREMENT BY 1
NO MINVALUE
NO MAXVALUE
CACHE 1
);
Now go to your Supabase Dashboard > SQL editor > New query and paste the commands copied above.
Click RUN and Magic! You will have the tables created for you in your database!
- Now go to your Supabase project Settings -> API -> and copy the Project URL and the Anon Key somewhere, we'll need them in the next steps.
Connect your local app with your newly created Shopify app in your partners account
- Open the terminal in your local project folder and run
shopify login
to make sure you are logged in with your cli in the same partner organization where you created the app. - Once you made sure you're logged in, create an
.env
file, leave all the values as they are here except for theSUPABASE_URL
andSUPABASE_ANON_KEY
as follow:
SHOPIFY_API_KEY=
SHOPIFY_API_SECRET=
SHOP=
SCOPES=write_products,write_customers,write_draft_orders // update this manually when you know which scopes you need for your app
HOST=
SUPABASE_URL=your Supabase url
SUPABASE_ANON_KEY=Your Supabase anon key
BUGSNAG_API_KEY=
VITE_SEGMENT_WRITE_KEY=
- Then, run the following command in your terminal:
shopify node serve
if you get the error "✗ Couldn't verify your store ", just run shopify node connect
to connect to your app and dev store.
-
The command will prompt you to choose a partner account and a development store to install the app on, and it will also ask you if you want to update your app url, choose Yes.
-
Go back yo your app in the Shopify Partners Account, go to App Setup and you will see thet the app url will be updated with an ngrok url like this one
https://yourngrokurl.ngrok.io/
. Copy that url and add the two following urls in the allowed redirection urls:yourngrokurl.ngrok.io/auth/token
andyourngrokurl.ngrok.io/auth/callback
and click on Save. -
After that, go back to your terminal and you will see that the CLI will provides you a url to install the app, click on the url and you will be prompted to install the app in your Shopify Store Admin, and execute the OAuth process.
-
And we're done!
If you check your Supabase Database, you will see 2 sessions saved, one is an online session, which is updated consistently and automatically, and one is an offline session which has a permament access token and it's used for interacting with the Store API in the background (e.g. Cron jobs and background jobs, etc.).
Also, you will see that your store is not an entry in your shops table rows.
The workflow for this app is based on local development and requires 2 commands to start and stop development:
shopify node serve
to start development- CTRL + C to stop the server
In order to create a production version of the app, you'll need to choose a hosting provider. For this example I will use Heroku CLI which makes it easy and quick to deploy changes.
- Create an Heroku account and install the CLI running
npm i -g heroku
. - Create a SECOND public app in your Shopify partner account. As App url and allowed redirect urls simply add
https://localhost/
for now. It's important to have two apps, one created previously for development and a new one ewhich will be your production app. I would suggest to call them differently, I simply use the same name and add "(development)" in the name of the one I use in development. - Back to Heroku,. create a new app and follow the steps displayed in the "Deploy using Heroku Git" section, it contains all the instructions to deploy your app. Note: before deploying, on the same page where you get the instruction, click in the settings tab and in the Config Vars section, click on Reveal config vars and add all your ENV variables you have in your project:
- SUPABASE_URL
- SUPABASE_ANON_KEY
- SHOPIFY_API_KEY -> copy this from your new app in your Shopify Partners Dashboard
- SHOPIFY_API_SECRET -> copy this from your new app in your Shopify Partners Dashboard
- HOST -> You will find your app url in the same page where you are setting your Config Vars, scrolling down to Domains. it usually looks like this: https://myapp.herokuapp.com/
- Back to your Shopify Partner Admin, go to your newly created app (the production one) and in your app setup, paste the url from Heroku in the App url (e.g https://myapp.herokuapp.com/), and in thew Allowed redirection URL(s)add the same url from heroku with the suffix /auth/token and auth/callback. e.g. https://myapp.herokuapp.com/auth/token and https://myapp.herokuapp.com/auth/callback.
And you're done. 🎉
Every time you work on your development app, you can just follow the workflow described above, and when you are ready to push your changes to production, you will simply need to commit and push your changes to Github as normal, and also run git push heroku to push your changes to your app and deploy the new changes to your hosted app.
This means, one code base but 2 apps, this is the most common workflow used by App Developers.
License
This repository is available as open source under the terms of the MIT License.