shopify_app 7.2.0 → 17.1.0

data/Gemfile.lock

@@ -0,0 +1,256 @@
+PATH
+  remote: .
+  specs:
+    shopify_app (17.1.0)
+      browser_sniffer (~> 1.2.2)
+      jwt (~> 2.2.1)
+      omniauth-shopify-oauth2 (~> 2.2.2)
+      rails (> 5.2.1, < 6.1)
+      redirect_safely (~> 1.0)
+      shopify_api (~> 9.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      activejob (= 6.0.3.5)
+      activerecord (= 6.0.3.5)
+      activestorage (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+      mail (>= 2.7.1)
+    actionmailer (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      actionview (= 6.0.3.5)
+      activejob (= 6.0.3.5)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.0.3.5)
+      actionview (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      activerecord (= 6.0.3.5)
+      activestorage (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.3.5)
+      activesupport (= 6.0.3.5)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.3.5)
+      activesupport (= 6.0.3.5)
+      globalid (>= 0.3.6)
+    activemodel (6.0.3.5)
+      activesupport (= 6.0.3.5)
+    activemodel-serializers-xml (1.0.2)
+      activemodel (> 5.x)
+      activesupport (> 5.x)
+      builder (~> 3.1)
+    activerecord (6.0.3.5)
+      activemodel (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+    activeresource (5.1.1)
+      activemodel (>= 5.0, < 7)
+      activemodel-serializers-xml (~> 1.0)
+      activesupport (>= 5.0, < 7)
+    activestorage (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      activejob (= 6.0.3.5)
+      activerecord (= 6.0.3.5)
+      marcel (~> 0.3.1)
+    activesupport (6.0.3.5)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.1)
+    binding_of_caller (0.8.0)
+      debug_inspector (>= 0.0.1)
+    browser_sniffer (1.2.2)
+    builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.8)
+    crack (0.4.4)
+    crass (1.0.6)
+    debug_inspector (0.0.3)
+    erubi (1.9.0)
+    faraday (1.3.0)
+      faraday-net_http (~> 1.0)
+      multipart-post (>= 1.2, < 3)
+      ruby2_keywords
+    faraday-net_http (1.0.1)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    graphql (1.12.5)
+    graphql-client (0.16.0)
+      activesupport (>= 3.0)
+      graphql (~> 1.8)
+    hashdiff (1.0.1)
+    hashie (4.1.0)
+    i18n (1.8.9)
+      concurrent-ruby (~> 1.0)
+    jwt (2.2.2)
+    loofah (2.7.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.2)
+    mimemagic (0.3.5)
+    mini_mime (1.0.2)
+    mini_portile2 (2.5.0)
+    minitest (5.14.4)
+    mocha (1.11.2)
+    multi_json (1.15.0)
+    multi_xml (0.6.0)
+    multipart-post (2.1.1)
+    nio4r (2.5.7)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    oauth2 (1.4.4)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    omniauth (1.9.1)
+      hashie (>= 3.4.6)
+      rack (>= 1.6.2, < 3)
+    omniauth-oauth2 (1.5.0)
+      oauth2 (~> 1.1)
+      omniauth (~> 1.2)
+    omniauth-shopify-oauth2 (2.2.3)
+      activesupport
+      omniauth-oauth2 (~> 1.5.0)
+    parallel (1.20.1)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-nav (0.3.0)
+      pry (>= 0.9.10, < 0.13.0)
+    pry-stack_explorer (0.4.9.3)
+      binding_of_caller (>= 0.7)
+      pry (>= 0.9.11)
+    public_suffix (4.0.6)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.0.3.5)
+      actioncable (= 6.0.3.5)
+      actionmailbox (= 6.0.3.5)
+      actionmailer (= 6.0.3.5)
+      actionpack (= 6.0.3.5)
+      actiontext (= 6.0.3.5)
+      actionview (= 6.0.3.5)
+      activejob (= 6.0.3.5)
+      activemodel (= 6.0.3.5)
+      activerecord (= 6.0.3.5)
+      activestorage (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+      bundler (>= 1.3.0)
+      railties (= 6.0.3.5)
+      sprockets-rails (>= 2.0.0)
+    rails-controller-testing (1.0.5)
+      actionpack (>= 5.0.1.rc1)
+      actionview (>= 5.0.1.rc1)
+      activesupport (>= 5.0.1.rc1)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.3.5)
+      actionpack (= 6.0.3.5)
+      activesupport (= 6.0.3.5)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    rb-readline (0.5.5)
+    redirect_safely (1.0.0)
+      activemodel
+    regexp_parser (2.0.0)
+    rexml (3.2.4)
+    rubocop (1.5.2)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.3.0)
+      parser (>= 2.7.1.5)
+    rubocop-shopify (1.0.7)
+      rubocop (~> 1.4)
+    ruby-progressbar (1.10.1)
+    ruby2_keywords (0.0.4)
+    shopify_api (9.4.0)
+      activeresource (>= 4.1.0, < 6.0.0)
+      graphql-client
+      rack
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.4.2)
+    thor (1.1.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.9)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
+    webmock (3.9.1)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  minitest
+  mocha
+  pry
+  pry-nav
+  pry-stack_explorer
+  rails-controller-testing
+  rake
+  rb-readline
+  rubocop-shopify
+  shopify_app!
+  sqlite3 (~> 1.4)
+  webmock
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -1,345 +1,130 @@
-Shopify App
-===========
-[![Version][gem]][gem_url] [![Build Status](https://travis-ci.org/Shopify/shopify_app.png)](https://travis-ci.org/Shopify/shopify_app)
+# Shopify App
+
+[![Version][gem]][gem_url] [![Build Status](https://github.com/Shopify/shopify_app/workflows/CI/badge.svg)](https://github.com/Shopify/shopify_app/actions?query=workflow%3ACI) ![Supported Rails version][supported_rails_version]
 
 [gem]: https://img.shields.io/gem/v/shopify_app.svg
 [gem_url]: https://rubygems.org/gems/shopify_app
+[supported_rails_version]: https://img.shields.io/badge/rails-%3C6.1.0-orange
 
+This gem builds Rails applications that can be embedded in the Shopify Admin.
 
-Shopify Application Rails engine and generator
-
-
-Table of Contents
------------------
-* [**Description**](#description)
-* [**Quickstart**](#quickstart)
-* [**Becoming a Shopify App Developer**](#becoming-a-shopify-app-developer)
-* [**Installation**](#installation)
-  * [Rails 5](#rails-5)
-* [**Generators**](#generators)
- * [Default Generator](#default-generator)
- * [Install Generator](#install-generator)
- * [Shop Model Generator](#shop-model-generator)
- * [Home Controller Generator](#home-controller-generator)
- * [App Proxy Controller Generator](#app-proxy-controller-generator)
- * [Controllers, Routes and Views](#controllers-routes-and-views)
-* [**Mounting the Engine**](#mounting-the-engine)
-* [**Managing Api Keys**](#managing-api-keys)
-* [**WebhooksManager**](#webhooksmanager)
-* [**ScripttagsManager**](#scripttagsmanager)
-* [**ShopifyApp::SessionRepository**](#shopifyappsessionrepository)
-* [**AuthenticatedController**](#authenticatedcontroller)
-* [**AppProxyVerification**](#appproxyverification)
- * [Recommended Usage](#recommended-usage)
-* [**Troubleshooting**](#troubleshooting)
- * [Generator shopify_app:install hangs](#generator-shopify_appinstall-hangs)
-* [**Testing an embedded app outside the Shopify admin**](#testing-an-embedded-app-outside-the-shopify-admin)
-* [**App Tunneling**](#app-tunneling)
-* [**Questions or problems?**](#questions-or-problems)
-
-
-Description
------------
-This gem includes a Rails Engine and generators for writing Rails applications using the Shopify API. The Engine provides a SessionsController and all the required code for authenticating with a shop via Oauth (other authentication methods are not supported).
-
-The [example](https://github.com/Shopify/shopify_app/tree/master/example) directory contains an app that was generated with this gem. It also contains sample code demonstrating the usage of the embedded app sdk.
-
-*Note: It's recommended to use this on a new Rails project, so that the generator won't overwrite/delete some of your files.*
-
-
-Quickstart
-----------
-
-Check out this screencast on how to create and deploy a new Shopify App to Heroku in 5 minutes:
-
-[https://vimeo.com/130247240](https://vimeo.com/130247240)
-
-Or if you prefer text instructions the steps in the video are written out [here](https://github.com/Shopify/shopify_app/blob/master/QUICKSTART.md)
+[Introduction](#introduction) | 
+[Requirements](#requirements) | 
+[Usage](#usage) | 
+[Documentation](#documentation) | 
+[Contributing](/CONTRIBUTING.md) |
+[License](/LICENSE)
 
-Becoming a Shopify App Developer
---------------------------------
-If you don't have a Shopify Partner account yet head over to http://shopify.com/partners to create one, you'll need it before you can start developing apps.
+## Introduction
 
-Once you have a Partner account create a new application to get an Api key and other Api credentials. To create a development application set the Application Callback URL to
+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](/docs/shopify_app/engine.md) provides all the code required to implement OAuth with Shopify. The [default Shopify App generator](/docs/shopify_app/generators.md#-environment-rails-generate-shopify_app) builds an app that can be embedded in the Shopify Admin and secures it with [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens).
 
-```
-http://localhost:3000/
-```
+<!-- This section is linked to in `templates/shopify_app.rb.tt`. Be careful renaming this heading. -->
+## Requirements
 
-and the `redirect_uri` to
+> **Rails compatibility** 
+> * Rails 6.1 or above is not yet supported due to the new `cookies_same_site_protection` setting. 
+> * Use Shopify App `<= v7.2.8` if you need to work with Rails 4.
 
-```
-http://localhost:3000/auth/shopify/callback
-```
+To become a Shopify app developer, you will need a [Shopify Partners](https://www.shopify.com/partners) account. Explore the [Shopify dev docs](https://shopify.dev/concepts/shopify-introduction) to learn more about [building Shopify apps](https://shopify.dev/concepts/apps).
 
-This way you'll be able to run the app on your local machine.
+This gem requires that you have the following credentials:
 
-Also note, ShopifyApp creates embedded apps by default, so remember to check `enabled` for the embedded settings.
+- **Shopify API key:** The API key app credential specified in your [Shopify Partners dashboard](https://partners.shopify.com/organizations). 
+- **Shopify API secret:** The API secret key app credential specified in your [Shopify Partners dashboard](https://partners.shopify.com/organizations). 
 
+## Usage
 
-Installation
-------------
-To get started add shopify_app to your Gemfile and bundle install
+1. To get started, create a new Rails app:
 
 ``` sh
-# Create a new rails app
 $ rails new my_shopify_app
-$ cd my_shopify_app
-
-# Add the gem shopify_app to your Gemfile
-$ echo "gem 'shopify_app'" >> Gemfile
-$ bundle install
-```
-
-Now we are ready to run any of the shopify_app generators. The following section explains the generators and what they can do.
-
-
-#### Rails 5
-
-shopify_app is compatible with Rails 5 but since the latest ActiveResource release (4.1) is locked on Rails 4.x, you'll need to use the unreleased master version:
-
-```ruby
-gem 'shopify_app'
-gem 'activeresource', github: 'rails/activeresource'
 ```
 
-
-Generators
-----------
-
-### Default Generator
-
-The default generator will run the `install`, `shop`, and `home_controller` generators. This is the recommended way to start your app.
+2. Add the Shopify App gem to `my_shopify_app`'s Gemfile.
 
 ```sh
-$ rails generate shopify_app --api_key <your_api_key> --secret <your_app_secret>
+$ bundle add shopify_app
 ```
 
+3. Create a `.env` file in the root of `my_shopify_app` to specify your Shopify API credentials:
 
-### Install Generator
-
-```sh
-$ rails generate shopify_app:install
-
-# or optionally with arguments:
-
-$ rails generate shopify_app:install --api_key <your_api_key> --secret <your_app_secret>
 ```
-
-Other options include:
-* `application_name` - the name of your app
-* `scope` - the Oauth access scope required for your app, eg 'read_products, write_orders'. For more information read the [docs](http://docs.shopify.com/api/tutorials/oauth)
-* `embedded` - the default is to generate an [embedded app](http://docs.shopify.com/embedded-app-sdk), if you want a legacy non-embedded app then set this to false, `--embedded false`
-
-You can update any of these settings later on easily, the arguments are simply for convenience.
-
-The generator adds ShopifyApp and the required initializers to the host Rails application.
-
-After running the `install` generator, you can start your app with `bundle exec rails server` and install your app by visiting localhost.
-
-
-### Shop Model Generator
-
-```sh
-$ rails generate shopify_app:shop_model
+SHOPIFY_API_KEY=<Your Shopify API key>
+SHOPIFY_API_SECRET=<Your Shopify API secret>
 ```
 
-The install generator doesn't create any database models for you and if you are starting a new app its quite likely that you will want one (most of our internally developed apps do!). This generator creates a simple shop model and a migration. It also creates a model called `SessionStorage` which interacts with `ShopifyApp::SessionRepository`. Check out the later section to learn more about `ShopifyApp::SessionRepository`
-
-*Note that you will need to run rake db:migrate after this generator*
+> In a development environment, you can use a gem like `dotenv-rails` to manage environment variables. 
 
-
-### Home Controller Generator
+4. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:
 
 ```sh
-$ rails generate shopify_app:home_controller
+$ rails generate shopify_app
 ```
 
-This generator creates an example home controller and view which fetches and displays products using the ShopifyAPI
-
-
-### App Proxy Controller Generator
+5. Run a migration to create the necessary tables in your database:
 
 ```sh
-$ rails generate shopify_app:app_proxy_controller
+$ rails db:migrate
 ```
 
-This optional generator, not included with the default generator, creates the app proxy controller to handle proxy requests to the app from your shop storefront, modifies 'config/routes.rb' with a namespace route, and an example view which displays current shop information using the LiquidAPI
-
-
-### Controllers, Routes and Views
-
-The last group of generators are for your convenience if you want to start overriding code included as part of the Rails engine. For example by default the engine provides a simple SessionController, if you run the `rails generate shopify_app:controllers` generator then this code gets copied out into your app so you can start adding to it. Routes and views follow the exact same pattern.
-
-Mounting the Engine
--------------------
-
-Mounting the Engine will provide the basic routes to authenticating a shop with your custom application. It will provide:
+6. Run the app:
 
-| Verb   | Route                         | Action                       |
-|--------|-------------------------------|------------------------------|
-|GET     |'/login'                       |Login                         |
-|POST    |'/login'                       |Login                         |
-|GET     |'/auth/shopify/callback'       |Authenticate Callback         |
-|GET     |'/logout'                      |Logout                        |
-|POST    |'/webhooks/:type'              |Webhook Callback              |
-
-
-The default routes of the Shopify rails engine, which is mounted to the root, can be altered to mount on a different route. The `config/routes.rb` can be modified to put these under a nested route (say `/app-name`) as:
-
-```ruby
-mount ShopifyApp::Engine, at: '/app-name'
-```
-
-This will create the Shopify engine routes under the specified Subdirectory, as a result it will redirect new consumers to `/app-name/login` and following a similar format for the other engine routes.
-
-To use named routes with the engine so that it can route between the application and the engine's routes it should be prefixed with `main_app` or `shopify_app`.
-
-```ruby
-main_app.login_path # For a named login route on the rails app.
-
-shopify_app.login_path # For the shopify app store login route.
-```
-
-Managing Api Keys
------------------
-
-The `install` generator places your Api credentials directly into the shopify_app initializer which is convenient and fine for development but once your app goes into production **your api credentials should not be in source control**. When we develop apps we keep our keys in environment variables so a production shopify_app initializer would look like this:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.application_name = 'Your app name' # Optional
-  config.api_key = ENV['SHOPIFY_CLIENT_API_KEY']
-  config.secret = ENV['SHOPIFY_CLIENT_API_SECRET']
-  config.scope = 'read_customers, read_orders, write_products'
-  config.embedded_app = true
-end
-```
-
-
-WebhooksManager
----------------
-
-ShopifyApp can manage your app's webhooks for you by setting which webhooks you require in the initializer:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.webhooks = [
-    {topic: 'carts/update', address: 'example-app.com/webhooks/carts_update'}
-  ]
-end
-```
-
-When the oauth callback is completed successfully ShopifyApp will queue a background job which will ensure all the specified webhooks exist for that shop. Because this runs on every oauth callback it means your app will always have the webhooks it needs even if the user uninstalls and re-installs the app.
-
-ShopifyApp also provides a WebhooksController that receives webhooks and queues a job based on the webhook url. For example if you register the webhook from above then all you need to do is create a job called `CartsUpdateJob`. The job will be queued with 2 params `shop_domain` and `webhook` which is the webhook body.
-
-If you'd rather implement your own controller then you'll want to use the WebhookVerfication module to verify your webhooks:
-
-```ruby
-class CustomWebhooksController < ApplicationController
-  include ShopifyApp::WebhookVerification
-
-  def carts_update
-    SomeJob.perform_later(shopify_domain: shop_domain, webhook: params)
-    head :ok
-  end
-end
-```
-
-The module skips the `verify_authenticity_token` before_action and adds an action to verify that the webhook came from Shopify.
-
-The WebhooksManager uses ActiveJob, if ActiveJob is not configured then by default Rails will run the jobs inline. However it is highly recommended to configure a proper background processing queue like sidekiq or resque in production.
-
-ShopifyApp can create webhooks for you using the `add_webhook` generator. This will add the new webhook to your config and create the required job class for you.
-
-```
-rails g shopify_app:add_webhook -t carts/update -a https://example.com/webhooks/carts_update
+```sh
+$ rails server
 ```
 
-where `-t` is the topic and `-a` is the address the webhook should be sent to.
-
-ScripttagsManager
------------------
-
-As with webhooks, ShopifyApp can manage your app's scripttags for you by setting which scripttags you require in the initializer:
+See [*Quickstart*](/docs/Quickstart.md) to learn how to install your app on a shop.
 
-```ruby
-ShopifyApp.configure do |config|
-  config.scripttags = [
-    {event:'onload', src: 'https://my-shopifyapp.herokuapp.com/fancy.js'}
-  ]
-end
-```
-
-Scripttags are created in the same way as the Webhooks, with a background job which will create the required scripttags.
+This app implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens) to authenticate merchants when embedded in the Shopify Admin.
 
-ShopifyApp::SessionRepository
------------------------------
+See [*Generators*](/docs/shopify_app/generators.md) for a complete list of generators available to Shopify App.
 
-`ShopifyApp::SessionRepository` allows you as a developer to define how your sessions are retrieved and stored for a shop. The `SessionRepository` is configured using the `config/initializers/shopify_session_repository.rb` file and can be set to any object that implements `self.store(shopify_session)` which stores the session and returns a unique identifier and `self.retrieve(id)` which returns a `ShopifyAPI::Session` for the passed id. See either the `InMemorySessionStore` or the `SessionStorage` module for examples.
+## Documentation
 
-If you only run the install generator then by default you will have an in memory store but it **won't work** on multi-server environments including Heroku. If you ran all the generators including the shop_model generator then the Shop model itself will be the `SessionRepository`. If you look at the implementation of the generated shop model you'll see that this gem provides an activerecord mixin for the `SessionRepository`. You can use this mixin on any model that responds to `shopify_domain` and `shopify_token`.
+You can find documentation on gem usage, concepts, mixins, installation, and more in [`/docs`](/docs).
 
-AuthenticatedController
------------------------
+* Start with the [*Generators*](/docs/shopify_app/generators.md) document to learn more about the generators this gem offers.
+* Check out the [*Changelog*](/CHANGELOG.md) for notes on the latest gem releases.
+* See [*Troubleshooting*](/docs/Troubleshooting.md) for tips on common issues.
+* If you are looking to upgrade your Shopify App version to a new major release, see [*Upgrading*](/docs/Upgrading.md) for important notes on breaking changes.
 
-The engine includes a controller called `ShopifyApp::AuthenticatedController` which inherits from `ApplicationController`. It adds some before_filters which ensure the user is authenticated and will redirect to the login page if not. It is best practice to have all controllers that belong to the Shopify part of your app inherit from this controller. The HomeController that is generated already inherits from AuthenticatedController.
+### Overview
 
-AppProxyVerification
---------------------
+[Quickstart](/docs/Quickstart.md)
 
-The engine provides a mixin for verifying incoming HTTP requests sent via an App Proxy. Any controller that `include`s `ShopifyApp::AppProxyVerification` will verify that each request has a valid `signature` query parameter that is calculated using the other query parameters and the app's shared secret.
+[Troubleshooting](/docs/Troubleshooting.md)
 
-### Recommended Usage
+[Upgrading](/docs/Upgrading.md)
 
-The App Proxy Controller Generator automatically adds the mixin to the generated app_proxy_controller.rb
-Additional controllers for resources within the App_Proxy namespace, will need to include the mixin like so:
+[Shopify App](/docs/shopify_app)
+  * [Authentication](/docs/shopify_app/authentication.md)
+  * [Engine](/docs/shopify_app/engine.md)
+  * [Generators](/docs/shopify_app/generators.md)
+  * [ScriptTags](/docs/shopify_app/script-tags.md)
+  * [Session repository](/docs/shopify_app/session-repository.md)
+  * [Handling changes in access scopes](/docs/shopify_app/handling-access-scopes-changes.md)
+  * [Testing](/docs/shopify_app/testing.md)
+  * [Webhooks](/docs/shopify_app/webhooks.md)
 
-```ruby
-# app/controllers/app_proxy/reviews_controller.rb
-class ReviewsController < ApplicationController
-  include ShopifyApp::AppProxyVerification
-  # ...
-end
-```
+### Engine
 
-Create your app proxy url in the [Shopify Partners' Dashboard](https://app.shopify.com/services/partners/api_clients), making sure to point it to `https://your_app_website.com/app_proxy`.
-![Creating an App Proxy](/images/app-proxy-screenshot.png)
-
-Troubleshooting
----------------
-
-### Generator shopify_app:install hangs
-
-Rails uses spring by default to speed up development. To run the generator, spring has to be stopped:
-
-```sh
-$ bundle exec spring stop
-```
-
-Run shopify_app generator again.
-
-Testing an embedded app outside the Shopify admin
--------------------------------------------------
-
-By default, loading your embedded app will redirect to the Shopify admin, with the app view loaded in an `iframe`. If you need to load your app outside of the Shopify admin (e.g., for performance testing), you can change `forceRedirect: false` to `true` in `ShopifyApp.init` block in the `embedded_app` view. To keep the redirect on in production but off in your `development` and `test` environments, you can use:
-
-```javascript
-forceRedirect: <%= Rails.env.development? || Rails.env.test? ? 'false' : 'true' %>
-```
+Mounting the Shopify App Rails Engine provides the following routes. These routes are configured to help install your application on shops and implement OAuth.
 
-App Tunneling
--------------
+| Verb   | Route                    | Action             |
+|   ---: | :---                     | :---               |
+| `GET`  | `/login`                 | Login              |
+| `POST` | `/login`                 | Login              |
+| `GET`  | `/auth/shopify/callback` | OAuth redirect URI |
+| `GET`  | `/logout`                | Logout             |
+| `POST` | `/webhooks/:type`        | Webhook callback   |
 
-For certain features like Application Proxy or Webhooks to receive requests from Shopify, your app needs to be on a publicly visible URL. This can be a hurdle during development or testing on a local machine. Fortunately, this can be overcome by employing a tunneling service like [Forward](https://forwardhq.com/), [RequestBin](requestb.in/), [ngrok](https://ngrok.com/) etc. These tools allow you to create a secure tunnel from the public Internet to your local machine.
+These routes are configurable. See the more detailed [*Engine*](/docs/shopify_app/engine.md) documentation to learn how you can customize the login URL or mount the Shopify App Rails engine at nested routes.
 
-Tunneling is also useful for working the the embedded app sdk to solve mixed content issues since most tunnles provide ssl.
+To learn more about how this gem authenticates with Shopify, see [*Authentication*](/docs/shopify_app/authentication.md).
 
-Questions or problems?
-----------------------
-http://api.shopify.com <= Read up on the possible API calls!
+### API Versioning
 
-http://ecommerce.shopify.com/c/shopify-apis-and-technology <= Ask questions!
+[Shopify's API is versioned](https://shopify.dev/concepts/about-apis/versioning). With Shopify App `v1.11.0`, the included Shopify API gem allows developers to specify and update the Shopify API version they want their app or service to use. The Shopify API gem also surfaces warnings to Rails apps about [deprecated endpoints, GraphQL fields and more](https://shopify.dev/concepts/about-apis/versioning#deprecation-practices).
 
-http://docs.shopify.com/api/the-basics/getting-started <= Read the docs!
+See the [Shopify API gem README](https://github.com/Shopify/shopify_api/) for more information.