Rails Shopify App Starter Kit

The Rails Shopify app with some tools for quick starting developing shopify app.

Tech Stack

This template combines a number of third party open source tools:

• BackEnd
  • Rails builds the backend.
• FrontEnd
  • Vite builds the React frontend.
  • React Router is used for routing. We wrap this with file-based routing.
  • React Query queries the Admin API.
  • i18next and related libraries are used to internationalize the frontend.
    • react-i18next is used for React-specific i18n functionality.
    • i18next-resources-to-backend is used to dynamically load app translations.
    • @formatjs/intl-localematcher is used to match the user locale with supported app locales.
    • @formatjs/intl-locale is used as a polyfill for Intl.Locale if necessary.
    • @formatjs/intl-pluralrules is used as a polyfill for Intl.PluralRules if necessary.
• Database: PostgreSQL
• Background Job:
  • Sidekiq
  • Redis

These third party tools are complemented by Shopify specific tools to ease app development:

• Shopify API library adds OAuth to the Rails backend. This lets users install the app and grant scope permissions.
• App Bridge and App Bridge React add authentication to API requests in the frontend and renders components outside of the App’s iFrame.
• Polaris React is a powerful design system and component library that helps developers build high quality, consistent experiences for Shopify merchants.
• Custom hooks make authenticated requests to the Admin API.
• File-based routing makes creating new pages easier.
• @shopify/i18next-shopify is a plugin for i18next that allows translation files to follow the same JSON schema used by Shopify app extensions and themes.

Gems

This includes gems like:

• dotenv-rails
• rubocop
• sentry-rails
• sentry-ruby
• sentry-sidekiq
• sidekiq

Requirements

1. You must create a Shopify partner account if you don’t have one.
2. You must create a store for testing if you don't have one, either a development store or a Shopify Plus sandbox store.
3. You must have Ruby installed.
4. You must have Bundler installed.
5. You must have Node.js installed.

Installation

1. git clone git@github.com:remy727/rails-shopify-app-starter-kit.git your-app-name
2. cd your-app-name
3. Install the ruby dependencies:

   cd web
   bundle install

4. Run the Rails template script. It will guide you through setting up your database and set up the necessary keys for encrypted credentials.

   bin/rails app:template LOCATION=./template.rb

5. Update SHOPIFY_API_KEY in heroku.yml.

And your Rails app is ready to run! You can now switch back to your app's root folder to continue:

cd ..

Local Development

The Shopify CLI connects to an app in your Partners dashboard. It provides environment variables, runs commands in parallel, and updates application URLs for easier development.

You can develop locally using your preferred Node.js package manager. Run one of the following commands from the root of your app:

Using yarn:

yarn dev

Using npm:

npm run dev

Using pnpm:

pnpm run dev

Open the URL generated in your console. Once you grant permission to the app, you can start development.

Heroku Deployment

Step 1: Set up hosting with Heroku

1. Download and install the Heroku CLI.
2. Navigate to your app directory:

cd my-app

3. Log in to the Heroku CLI:

heroku login

4. Log in to the Heroku Container Registry:

heroku container:login

5. Create an app in Heroku:

heroku create -a <my-app-name> -s container

Step 2: Add addons

• Heroku Postgres
• Heroku Data for Redis

Step 3: Set environment variables

The following environment variables need to be provided for all apps:

Variable	Secret?	Required	Value	Description
HOST	Yes	Yes	string	Heroku App Domain
RAILS_MASTER_KEY	Yes	Yes	string	Use value from web/config/master.key or create a new one.
RAILS_ENV		Yes	"production"
RAILS_SERVE_STATIC_FILES		Yes	1	Tells rails to serve the React app from the public folder.
RAILS_LOG_TO_STDOUT		Yes	1	Tells rails to print out logs.
SENTRY_CURRENT_ENV			string	Sentry Environment
SENTRY_DSN			string	Sentry DSN
SENTRY_TRACES_SAMPLE_RATE			float	Sentry Sample Rate
SHOPIFY_API_KEY			string	The client ID of the app, retrieved using Shopify CLI.
SHOPIFY_API_SCOPES			string	The app's access scopes, retrieved using Shopify CLI.
SHOPIFY_API_SECRET			string	The client secret of the app, retrieved using Shopify CLI.
SHOPIFY_APP_NAME			string	Shopify App Name

Step 3: Deploy your app

git push heroku main

Step 4: Update URLs in the Partner Dashboard

1. From the Partner Dashboard, go to Apps.
2. Select the app that you deployed to your hosting provider.
3. On the App setup page, in the URLs section, update the App URL and Allowed redirection URL(s) settings.

• App URL: The base URL of your app. This URL should match your HOST environment variable.
• Allowed redirection URL(s): The callback URL for your app. This is usually the same as the app URL, with /api/auth/callback appended.

The following are examples of URLs that you might set for Heroku:

• App URL: https://my-app.herokuapp.com
• Allowed redirection URL(s): https://my-app.herokuapp.com/api/auth/callback

Step 5: Enjoy your app :)