Shopify App

This gem builds Rails applications that can be embedded in the Shopify Admin.

Introduction | Requirements | Usage | Documentation | Contributing | License

Introduction

This gem includes a Rails engine, generators, modules, and mixins that help create Rails applications that work with Shopify APIs. The Shopify App Rails engine provides all the code required to implement OAuth with Shopify. The default Shopify App generator builds an app that can be embedded in the Shopify Admin and secures it with session tokens.

Requirements

To become a Shopify app developer, you will need a Shopify Partners account. Explore the Shopify dev docs to learn more about building Shopify apps.

This gem requires that you have the following credentials:

• Shopify API key: The API key app credential specified in your Shopify Partners dashboard.
• Shopify API secret: The API secret key app credential specified in your Shopify Partners dashboard.

Usage

[!NOTE] This package works best with the Shopify CLI. Learn more at https://shopify.dev/docs/apps/build/cli-for-apps

To get started with a Rails app already connected to the Shopify CLI, run shopify app init --template=ruby for a complete setup app. (Recommended) Follow the instructions below to use this gem with a new or existing Rails app.

1. To get started, create a new Rails app:

rails new my_shopify_app

2. Add the Shopify App gem to the app's Gemfile:

bundle add shopify_app

3. Connect the Shopify CLI to your app:

Setting up Shopify CLI

For a more detailed guide on how to set up Shopify CLI, see the Shopify CLI documentation.

To use your Rails app with Shopify CLI, you'll need to create the required configuration files and set up your project structure:

1. Create a package.json file in your app's root directory:

{
  "name": "my-shopify-app",
  "version": "1.0.0",
  "description": "Shopify app built with Rails",
  "scripts": {},
  "dependencies": {},
  "engines": {
    "node": ">=18.0.0"
  }
}

This is required for the Shopify CLI to work. It will be used if you add extension like Checkout UI extensions to your app.

2. Create a shopify.app.toml configuration file in your app's root:

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

client_id = ""
name = "My Shopify App"
handle = "my-shopify-app"
application_url = "https://localhost:3000"
embedded = true

[access_scopes]
# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
scopes = "write_products"

[auth]
redirect_urls = [
  "https://localhost:3000/api/auth",
  "https://localhost:3000/api/auth/callback",
  "https://localhost:3000/auth/callback",
  "https://localhost:3000/auth/shopify/callback"
]

[webhooks]
api_version = "2024-10"

[[webhooks.subscriptions]]
topics = ["app/uninstalled"]
uri = "/api/webhooks"

[pos]
embedded = false

[build]
automatically_update_urls_on_dev = true
dev_store_url = "YOUR-DEV-STORE.myshopify.com"

3. Create a shopify.web.toml file to configure how Shopify CLI runs your Rails app:

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

[commands]
dev = "bin/rails server -b 0.0.0.0 -e development"
build = "RAILS_ENV=production bin/rails assets:precompile"

4. (Optional) Update your Rails development configuration to allow Shopify's tunnel hosts. In config/environments/development.rb, add:

Rails.application.configure do
  # Allow ngrok tunnels for secure Shopify OAuth redirects
  config.hosts = (config.hosts rescue []) << /[-\w]+\.ngrok\.io/
  # Allow Cloudflare tunnels for secure Shopify OAuth redirects
  config.hosts = (config.hosts rescue []) << /[-\w]+\.trycloudflare\.com/
  
  # Or to allow all hosts in development (less secure):
  # config.hosts.clear
  
  # ... rest of your configuration
end

With the Shopify CLI you can use localhost development to run your app.

5. Generate your API credentials

shopify app config link
> create a new app

6. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:

rails generate shopify_app

7. Run a migration to create the necessary tables in your database:

rails db:migrate

8. Start the dev server and install the app

shopify app dev

Clink on the Preview URL to install the app and view it in the Shopify Admin

This app implements OAuth 2.0 Token Exchange with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use session tokens to authenticate merchants when embedded in the Shopify Admin.

See Generators for a complete list of generators available to Shopify App.

Documentation

You can find documentation on gem usage, concepts, mixins, installation, and more in /docs.

This is the beginning of the README. Read the rest at the original. Read the full README ↗