Getting Started
Welcome to our project! This guide will walk you through setting up the project on your local machine for development and testing purposes.
Prerequisites
Before you begin, ensure you have the following installed:
- Node.js 22.2.0 or later: Our project requires Node.js version 22.2.0 or later. You can download it from the official Node.js website or use a node version manager like nvm, asdf or development environment setup tool such as mise-en-place
- pnpm: Our package management tool. Make sure it's installed and configured on your system.
Installation
- Clone the Project: Start by cloning the repository to your local machine. Use the following command to clone:
git clone git@github.com:baoagency/shopify-app-template.git <project-name>
Navigate into the project directory:
cd <project-name>
- Install Dependencies: Run the following command to install the necessary dependencies:
pnpm install
- Setup Cloudflare Services: Our project utilizes Cloudflare's D1, R2, Cloudflare KV, and Cloudflare Queues. To set up these services, run:
pnpm run setup
This command configures the necessary Cloudflare services the app requires.
Configuration
To link your development environment with a development version of the app, run the below. If this is your first time running this command, you should create a new app following a naming convention of "[Merchant name] by BAO (Dev [developer initials])".
pnpm run shopify app config link
Once this is linked you'll need to go into the created file, normally shopify.app.toml and add:
[access_scopes]
# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
scopes = "read_locales,write_checkout_branding_settings,write_files"
Amend the application URL: application_url = "https://{your-app-name}.beeayo.com/"
Amend the redirect_urls URL: redirect_urls = [ "https://{your-app-name}.beeayo.com/api/auth" ]
Then push the changes to the app by running pnpm run shopify app deploy.
Running the Project
pnpm run dev
This command starts the local development server, allowing you to test and develop features in real-time.
Choose Yes when presented with the option to automatically update URLs in the shopify.app.toml file.
Ensure you've logged into the store before trying to install the app otherwise you'll be presented with an error.
Deployment
When you're ready to deploy your project, run:
pnpm run deploy
This command prepares and deploys your project to production, utilizing Cloudflare's infrastructure for hosting.
We'll then need to create a new app in the Shopify Partner Dashboard. This will be the live app that will go on their stores. To do this follow the configuration step above. Ensure the app is set to the same name as the development app but without the (Dev) at the end. Also ensure the file created is called shopify.app.production.toml Make sure the scopes in that new file match what are in the shopify.app.toml. You'll also need to update the application_url and redirect_urls to the live URL that you got from the pnpm run deploy command.
Once that's done you'll need to run the following command to update the shopify config
pnpm run shopify app deploy
Once this is done we'll need to just set all of the secrets for the app. To do this we'll need to run the following command:
pnpm run shopify app env show
This will show you the values that you need to set for the app. Note these down. Then navigate to the Cloudflare admin -> Workers & Pages -> Select your worker -> Settings -> Environment variables.
Once you're there proceed to add the follow 4 variables.
SHOPIFY_API_KEY
SHOPIFY_API_SECRET
SHOPIFY_APP_URL
SCOPES
You will be able to get the SHOPIFY_API_KEY, SHOPIFY_API_SECRET & SCOPES from the shopify app env show command. The SHOPIFY_APP_URL will be the URL that you were provided when you deployed your app. You will be able to see it on the "Deployments" tab within your worker in your admin. It's typically https://your-app-name.by-association-only.workers.dev.
Finally, run the migrations to set up the D1 database:
pnpm run db:migrate