A beginner’s guide to setting up your first Shopify app using Ruby on Rails

Hi there, my name is Jeroen, and this is my first article on dev.to.

I am a Senior Ruby on Rails developer, and over time I have ended up building quite a few Shopify apps. If you are curious about Shopify app development and have at least touched Ruby on Rails before, this article should be a nice starting point.

We are not going to discuss every possible concept around Shopify apps yet. That would just make this article much longer and more confusing than it needs to be.

Instead, we are going to do the most important thing first:

set up a brand new Shopify app using Ruby on Rails and get it running locally.

This article can serve as a reference if you just want to get your first app up and running and have a look around.

Introduction

For this guide, I am assuming a few things:

• you already have Ruby on Rails installed
• you already have Node.js installed
• you already have Git installed
• you are comfortable using your terminal
• you have a Shopify Partner account and a development store

You do not need to be deeply experienced with Rails yet. It is enough if you roughly know what Rails is and how to run commands in a project.

If you do not have the Shopify side set up yet, you will need a Partner account and a development store before you can properly install and test your app.

For this guide, we are going to use Shopify’s maintained Ruby app template. This is currently one of the nicest ways to get started quickly, because it already includes a Rails backend, Shopify authentication, session storage, Admin API access, and webhook support. The template does also include a React frontend, but that is fine. We can mostly treat that as already wired up for us while we focus on the Rails side first.

Part 1: Installing Shopify CLI

Before we create the app, we need Shopify CLI.

Shopify CLI is the command line tool that helps create Shopify apps, manage app extensions, create tunnels for local development, and connect your local project to Shopify.

You can install it globally by running:

npm install -g @shopify/cli@latest

Once that is done, it is a good idea to check if it worked:

shopify version

If that gives you a version number, you are good to go.

Part 2: Creating the app

Now that we have Shopify CLI installed, we can use Shopify’s Ruby template to create our app.

Run:

shopify app init --template=https://github.com/Shopify/shopify-app-template-ruby

The template is specifically for building a Shopify app using Ruby on Rails and React.

The CLI will ask you a few questions while setting everything up. Just follow along and choose a name for your app.

Once it is done, navigate into the folder it created:

cd your-app-name

You now have a Shopify app on your machine.

Part 3: Starting the app locally

This is the nice part.

From the root of your new app, run:

shopify app dev

When you run this for the first time, Shopify CLI will guide you through connecting the project to an app and development store.

After a bit of setup, it will print a URL in the terminal.

Open that URL in your browser and install the app on your development store.

At that point, your app should be running.

That is already a big step. A lot of the mystery disappears once you have a real app running and can click around in it.

Part 4: What we just created

It helps to understand what this template already gave us.

Shopify’s Ruby template comes with these things out of the box:

• OAuth for app installation and permissions
• GraphQL Admin API access
• REST Admin API access
• webhooks
• the shopify_app Rails engine
• the shopify_api gem
• session storage through Rails / ActiveRecord

That sounds like a lot, but really it just means a bunch of the annoying setup work has already been done for us.

This is exactly why I like starting from the template instead of wiring everything by hand in a first guide.

Part 5: Having a look around the project

Now that the app is running, let’s have a quick look at some of the files and folders you will actually care about in the beginning.

We are not going to discuss every file. That would be a bit much for now.

The shopify.app.toml file

This file is very important.

Shopify CLI uses it as part of the conventional app structure for Shopify apps. It holds app configuration that Shopify CLI uses when running and managing the app.

You do not need to fully understand it yet, but it is good to know that this file is one of the central pieces that connects your local app to Shopify CLI.

The web folder

This is where the actual web app lives.

In the Ruby template, Rails builds the backend, and the frontend lives inside this same project structure.

This means that when you want to look at the application code, this is where you will spend most of your time.

The web/app/controllers folder

This folder contains controllers.

If you are new to Rails, a controller is basically the part that receives a request and decides what should happen next.

In a Shopify app, this might mean:

• returning data to the frontend
• handling an action from the merchant
• talking to Shopify through the API
• calling a service object

You do not need to master controllers yet. Just know that they often act as the entry point for requests.

The web/app/services folder

This is often where you put code that does the actual work.

For example, instead of putting a lot of logic directly inside a controller, you might move that logic into a service object.

That can make the app easier to read, because the controller stays smaller and the heavier logic lives somewhere more focused.

So a simple way to think about it is:

• controllers receive the request
• services do the work

That is not a perfect description of every Rails app, but it is a very helpful starting point.

The web/config folder

This is where your routes and general configuration live.

The routes file is especially useful early on, because it helps you understand what URLs in your app go where.

If you are still new to Rails, routes.rb is a very nice file to open because it gives you a map of the app.

Part 6: Making your first small change

At this point, I like making one tiny change just to get comfortable.

You can, for example, open the project in your editor and start by looking at:

• web/config/routes.rb
• web/app/controllers
• web/app/services

You do not need to fully understand the whole app yet.

Just get used to the fact that underneath the Shopify-specific tooling, there is still a Rails app in there.

That is one of the most helpful mindset shifts in the beginning.

A Shopify app is not some completely magical thing.

It is a web application with Shopify-specific authentication, API access, and extension points.

Part 7: Making your first Shopify API call

Once your app is running, the next fun step is making a Shopify API call.

The Ruby template points to built-in examples for this, including Admin GraphQL and Admin REST API requests.

The current basic shape of an Admin GraphQL client looks like this:

client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
response = client.query(query: query)

That is the core shape you will keep seeing when you make authenticated Admin API requests from Ruby.

You do not need to understand every part of this line right away.

For now, the main thing to notice is:

• a client is created
• that client uses the current Shopify session
• a query is sent to Shopify
• a response comes back

That is the basic loop.

For a first day, I would not try to build a giant feature yet.

I would simply:

• get the app running
• find one example API call
• follow how the request flows through the Rails app
• make one small change and see what happens

That is enough to start building intuition.

Conclusion

We now have a Shopify app running locally using Ruby on Rails.

That is already a really nice place to start.

We installed Shopify CLI, created a new app from Shopify’s Ruby template, ran it locally, installed it on a development store, and had a quick look at the parts of the project that matter most in the beginning.

At this point, the best thing you can do is just spend a bit of time clicking around, opening files, and getting comfortable with the shape of the app. Once you see that it is still just a Rails application with some Shopify-specific pieces around it, things start feeling much more approachable.

I write more about Ruby on Rails, Shopify, and building practical things for merchants on Instasupport, so if you want more guides like this, you can find them for free with no ads and no paywall here: Instasupport.io Guides.