Skip to content

ultrarslanoglu/shopify-app-template-ruby

 
 

Repository files navigation

Shopify App Template - Ruby

This is a template for building a Shopify app using Ruby on Rails and React. It contains the basics for building a Shopify app.

Rather than cloning this repo, you can use your preferred package manager and the Shopify CLI with these steps.

Benefits

Shopify apps are built on a variety of Shopify tools to create a great merchant experience. The create an app tutorial in our developer documentation will guide you through creating a Shopify app using this template.

The Ruby app template comes with the following out-of-the-box functionality:

  • OAuth: Installing the app and granting permissions
  • GraphQL Admin API: Querying or mutating Shopify admin data
  • REST Admin API: Resource classes to interact with the API
  • Shopify-specific tooling:
    • AppBridge
    • Polaris
    • Webhooks

Tech Stack

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

Tool Usage
Shopify App Rails engine to help build Shopify app using Rails conventions. Helps to install your application on shops, and provides tools for:
  • OAuth
  • Session Storage
  • Webhook Processing
  • etc.
  • ShopifyAPI Gem A lightweight gem to provide tools for:
  • Obtaining an active session. (ShopifyApp uses this behind the scenes to handle OAuth)
  • Clients to make request to Shopify GraphQL and Rest APIs. See how it's used here
  • Error handling
  • Application Logger
  • Webhook Management
  • App Bridge,
    App Bridge React
    Frontend library that:
  • Add authentication to API requests in the frontend
  • Renders components outside of the App’s iFrame in Shopify's Admin page
  • Custom React hooks Custom React hooks that uses App Bridge to make authenticated requests to the Admin API.
    Polaris React A powerful design system and react component library that helps developers build high quality, consistent experiences for Shopify merchants.
    File-based routing Tool makes creating new pages easier.
    @shopify/i18next-shopify A plugin for i18next that allows translation files to follow the same JSON schema used by Shopify app extensions and themes.

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

    Getting started

    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.

    Installing the template

    This template runs on Shopify CLI 3.0, which is a node package that can be included in projects. You can install it using your preferred Node.js package manager:

    Using yarn:

    yarn create @shopify/app --template=ruby

    Using npx:

    npm init @shopify/app@latest -- --template=ruby

    Using pnpm:

    pnpm create @shopify/app@latest --template=ruby

    This will clone the template and install the CLI in that project.

    Setting up your Rails app

    Once the Shopify CLI clones the repo, you will be able to run commands on your app. However, the CLI will not manage your Ruby dependencies automatically, so you will need to go through some steps to be able to run your app. To make the process easier, the template provides a script to run the necessary steps:

    1. Start off by switching to the web folder:
      cd web
    2. Install the ruby dependencies:
      bundle install
    3. 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

    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.

    Deployment

    Application Storage

    This template uses Rails' ActiveRecord framework to store Shopify session data. It provides migrations to create the necessary tables in your database, and it stores and loads session data from them.

    The database that works best for you depends on the data your app needs and how it is queried. You can run your database of choice on a server yourself or host it with a SaaS company. Once you decide which database to use, you can configure your app to connect to it, and this template will start using that database for session storage.

    Build

    The frontend is a single page React app. It requires the SHOPIFY_API_KEY environment variable, which you can get by running yarn run info --web-env. The CLI will set up the necessary environment variables for the build if you run its build command from your app's root:

    Using yarn in your app's root folder:

    yarn build --api-key=REPLACE_ME

    Using npm:

    npm run build --api-key=REPLACE_ME

    Using pnpm:

    pnpm run build --api-key=REPLACE_ME

    The app build command will build both the frontend and backend when running as above. If you're manually building (for instance when deploying the web folder to production), you'll need to build both of them:

    cd web/frontend
    SHOPIFY_API_KEY=REPLACE_ME yarn build
    cd ..
    rake build:all

    Making your first API call

    You can use the ShopifyAPI gem to start make authenticated Shopify API calls.

    Examples from this app template:

    • Making Admin GraphQL API request to create products:
      • ProductCreator#create (web/app/services/product_creator.rb)
    • Making Admin Rest API request to count products:
      • ProductsController#count (web/app/controllers/products_controller.rb)

    Hosting

    When you're ready to set up your app in production, you can follow our deployment documentation to host your app on a cloud provider like Heroku or Fly.io.

    When you reach the step for setting up environment variables, you also need to set the following variables:

    Variable Secret? Required Value Description
    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 1 Tells rails to print out logs.

    Known issues

    Hot module replacement and Firefox

    When running the app with the CLI in development mode on Firefox, you might see your app constantly reloading when you access it. That happened in previous versions of the CLI, because of the way HMR websocket requests work.

    We fixed this issue with v3.4.0 of the CLI, so after updating it, you can make the following changes to your app's web/frontend/vite.config.js file:

    1. Change the definition hmrConfig object to be:

      const host = process.env.HOST
        ? process.env.HOST.replace(/https?:\/\//, "")
        : "localhost";
      
      let hmrConfig;
      if (host === "localhost") {
        hmrConfig = {
          protocol: "ws",
          host: "localhost",
          port: 64999,
          clientPort: 64999,
        };
      } else {
        hmrConfig = {
          protocol: "wss",
          host: host,
          port: process.env.FRONTEND_PORT,
          clientPort: 443,
        };
      }
    2. Change the server.host setting in the configs to "localhost":

      server: {
        host: "localhost",
        ...

    I can't get past the ngrok "Visit site" page

    When you’re previewing your app or extension, you might see an ngrok interstitial page with a warning:

    You are about to visit <id>.ngrok.io: Visit Site
    

    If you click the Visit Site button, but continue to see this page, then you should run dev using an alternate tunnel URL that you run using tunneling software. We've validated that Cloudflare Tunnel works with this template.

    To do that, you can install the cloudflared CLI tool, and run:

    # Note that you can also use a different port
    cloudflared tunnel --url http://localhost:3000

    In a different terminal window, navigate to your app's root and call:

    # Using yarn
    yarn dev --tunnel-url https://tunnel-url:3000
    # or using npm
    npm run dev --tunnel-url https://tunnel-url:3000
    # or using pnpm
    pnpm dev --tunnel-url https://tunnel-url:3000

    I'm seeing "App couldn't be loaded" error due to browser cookies

    Using yarn:

    yarn dev --reset

    Using npm:

    npm run dev -- --reset

    Using pnpm:

    pnpm run dev --reset

    Developer resources

    About

    No description, website, or topics provided.

    Resources

    Stars

    Watchers

    Forks

    Releases

    No releases published

    Packages

    No packages published

    Languages

    • Ruby 79.5%
    • HTML 14.9%
    • JavaScript 2.7%
    • CSS 1.5%
    • Other 1.4%