{"id":20178244,"url":"https://github.com/esterified/ruby-shopify-app","last_synced_at":"2025-06-24T06:08:29.393Z","repository":{"id":248236629,"uuid":"587747649","full_name":"esterified/ruby-shopify-app","owner":"esterified","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-11T13:49:37.000Z","size":180,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-03T05:29:33.506Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esterified.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-11T13:48:36.000Z","updated_at":"2024-11-28T12:06:57.000Z","dependencies_parsed_at":"2024-07-13T10:49:52.217Z","dependency_job_id":null,"html_url":"https://github.com/esterified/ruby-shopify-app","commit_stats":null,"previous_names":["esterified/ruby-shopify-app"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/esterified/ruby-shopify-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esterified%2Fruby-shopify-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esterified%2Fruby-shopify-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esterified%2Fruby-shopify-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esterified%2Fruby-shopify-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esterified","download_url":"https://codeload.github.com/esterified/ruby-shopify-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esterified%2Fruby-shopify-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261618133,"owners_count":23185096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T02:20:00.730Z","updated_at":"2025-06-24T06:08:29.368Z","avatar_url":"https://github.com/esterified.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopify App Template - Ruby\n\nThis is a template for building a [Shopify app](https://shopify.dev/apps/getting-started) using Ruby on Rails and React. It contains the basics for building a Shopify app.\n\nRather than cloning this repo, you can use your preferred package manager and the Shopify CLI with [these steps](#installing-the-template).\n\n## Benefits\n\nShopify apps are built on a variety of Shopify tools to create a great merchant experience. The [create an app](https://shopify.dev/apps/getting-started/create) tutorial in our developer documentation will guide you through creating a Shopify app using this template.\n\nThe Ruby app template comes with the following out-of-the-box functionality:\n\n- OAuth: Installing the app and granting permissions\n- GraphQL Admin API: Querying or mutating Shopify admin data\n- REST Admin API: Resource classes to interact with the API\n- Shopify-specific tooling:\n  - AppBridge\n  - Polaris\n  - Webhooks\n\n## Tech Stack\n\nThis template combines a number of third party open source tools:\n\n- [Rails](https://rubyonrails.org/) builds the backend.\n- [Vite](https://vitejs.dev/) builds the [React](https://reactjs.org/) frontend.\n- [React Router](https://reactrouter.com/) is used for routing. We wrap this with file-based routing.\n- [React Query](https://react-query.tanstack.com/) queries the Admin API.\n\nThese third party tools are complemented by Shopify specific tools to ease app development:\n\n- [Shopify API library](https://github.com/Shopify/shopify-api-ruby) adds OAuth to the Rails backend. This lets users install the app and grant scope permissions.\n- [App Bridge](https://shopify.dev/apps/tools/app-bridge) and [App Bridge React](https://shopify.dev/apps/tools/app-bridge/getting-started/using-react) add authentication to API requests in the frontend and renders components outside of the App’s iFrame.\n- [Polaris React](https://polaris.shopify.com/) is a powerful design system and component library that helps developers build high quality, consistent experiences for Shopify merchants.\n- [Custom hooks](https://github.com/Shopify/shopify-frontend-template-react/tree/main/hooks) make authenticated requests to the Admin API.\n- [File-based routing](https://github.com/Shopify/shopify-frontend-template-react/blob/main/Routes.jsx) makes creating new pages easier.\n\n## Getting started\n\n### Requirements\n\n1. You must [create a Shopify partner account](https://partners.shopify.com/signup) if you don’t have one.\n1. You must [create a development store](https://help.shopify.com/en/partners/dashboard/development-stores#create-a-development-store) if you don’t have one.\n1. You must have [Ruby](https://www.ruby-lang.org/en/) installed.\n1. You must have [Bundler](https://bundler.io/) installed.\n1. You must have [Node.js](https://nodejs.org/) installed.\n\n### Installing the template\n\nThis 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:\n\nUsing yarn:\n\n```shell\nyarn create @shopify/app --template=ruby\n```\n\nUsing npx:\n\n```shell\nnpm init @shopify/app@latest --template=ruby\n```\n\nUsing pnpm:\n\n```shell\npnpm create @shopify/app@latest --template=ruby\n```\n\nThis will clone the template and install the CLI in that project.\n\n### Setting up your Rails app\n\nOnce the Shopify CLI clones the repo, you will be able to run commands on your app.\nHowever, 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.\nTo make the process easier, the template provides a script to run the necessary steps:\n\n1. Start off by switching to the `web` folder:\n   ```shell\n   cd web\n   ```\n1. Install the ruby dependencies:\n   ```shell\n   bundle install\n   ```\n1. Run the [Rails template](https://guides.rubyonrails.org/rails_application_templates.html) script.\n   It will guide you through setting up your database and set up the necessary keys for encrypted credentials.\n   ```shell\n   bin/rails app:template LOCATION=./template.rb\n   ```\n\nAnd your Rails app is ready to run! You can now switch back to your app's root folder to continue:\n\n```shell\ncd ..\n```\n\n### Local Development\n\n[The Shopify CLI](https://shopify.dev/apps/tools/cli) connects to an app in your Partners dashboard.\nIt provides environment variables, runs commands in parallel, and updates application URLs for easier development.\n\nYou can develop locally using your preferred Node.js package manager.\nRun one of the following commands from the root of your app:\n\nUsing yarn:\n\n```shell\nyarn dev\n```\n\nUsing npm:\n\n```shell\nnpm run dev\n```\n\nUsing pnpm:\n\n```shell\npnpm run dev\n```\n\nOpen the URL generated in your console. Once you grant permission to the app, you can start development.\n\n## Deployment\n\n### Application Storage\n\nThis template uses [Rails' ActiveRecord framework](https://guides.rubyonrails.org/active_record_basics.html) to store Shopify session data.\nIt provides migrations to create the necessary tables in your database, and it stores and loads session data from them.\n\nThe database that works best for you depends on the data your app needs and how it is queried.\nYou can run your database of choice on a server yourself or host it with a SaaS company.\nOnce 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.\n\n### Build\n\nThe frontend is a single page React app.\nIt requires the `SHOPIFY_API_KEY` environment variable, which you can get by running `yarn run info --web-env`.\nThe CLI will set up the necessary environment variables for the build if you run its `build` command from your app's root:\n\nUsing yarn in your app's root folder:\n\n```shell\nyarn build --api-key=REPLACE_ME\n```\n\nUsing npm:\n\n```shell\nnpm run build --api-key=REPLACE_ME\n```\n\nUsing pnpm:\n\n```shell\npnpm run build --api-key=REPLACE_ME\n```\n\nThe app build command will build both the frontend and backend when running as above.\nIf you're manually building (for instance when deploying the `web` folder to production), you'll need to build both of them:\n\n```shell\ncd web/frontend\nSHOPIFY_API_KEY=REPLACE_ME yarn build\ncd ..\nrake build:all\n```\n\n## Hosting\n\nWhen you're ready to set up your app in production, you can follow [our deployment documentation](https://shopify.dev/apps/deployment/web) to host your app on a cloud provider like [Heroku](https://www.heroku.com/) or [Fly.io](https://fly.io/).\n\nWhen you reach the step for [setting up environment variables](https://shopify.dev/apps/deployment/web#set-env-vars), you also need to set the following variables:\n\n| Variable                   | Secret? | Required |     Value      | Description                                                 |\n| -------------------------- | :-----: | :------: | :------------: | ----------------------------------------------------------- |\n| `RAILS_MASTER_KEY`         |   Yes   |   Yes    |     string     | Use value from `web/config/master.key` or create a new one. |\n| `RAILS_ENV`                |         |   Yes    | `\"production\"` |                                                             |\n| `RAILS_SERVE_STATIC_FILES` |         |   Yes    |      `1`       | Tells rails to serve the React app from the public folder.  |\n| `RAILS_LOG_TO_STDOUT`      |         |          |      `1`       | Tells rails to print out logs.                              |\n\n## Known issues\n\n### Hot module replacement and Firefox\n\nWhen running the app with the CLI in development mode on Firefox, you might see your app constantly reloading when you access it.\nThat happened in previous versions of the CLI, because of the way HMR websocket requests work.\n\nWe 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:\n\n1. Change the definition `hmrConfig` object to be:\n\n   ```js\n   const host = process.env.HOST\n     ? process.env.HOST.replace(/https?:\\/\\//, \"\")\n     : \"localhost\";\n\n   let hmrConfig;\n   if (host === \"localhost\") {\n     hmrConfig = {\n       protocol: \"ws\",\n       host: \"localhost\",\n       port: 64999,\n       clientPort: 64999,\n     };\n   } else {\n     hmrConfig = {\n       protocol: \"wss\",\n       host: host,\n       port: process.env.FRONTEND_PORT,\n       clientPort: 443,\n     };\n   }\n   ```\n\n1. Change the `server.host` setting in the configs to `\"localhost\"`:\n\n   ```js\n   server: {\n     host: \"localhost\",\n     ...\n   ```\n\n### I can't get past the ngrok \"Visit site\" page\n\nWhen you’re previewing your app or extension, you might see an ngrok interstitial page with a warning:\n\n```\nYou are about to visit \u003cid\u003e.ngrok.io: Visit Site\n```\n\nIf 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.\nWe've validated that [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/run-tunnel/trycloudflare/) works with this template.\n\nTo do that, you can [install the `cloudflared` CLI tool](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/), and run:\n\n```shell\n# Note that you can also use a different port\ncloudflared tunnel --url http://localhost:3000\n```\n\nIn a different terminal window, navigate to your app's root and call:\n\n```shell\n# Using yarn\nyarn dev --tunnel-url https://tunnel-url:3000\n# or using npm\nnpm run dev --tunnel-url https://tunnel-url:3000\n# or using pnpm\npnpm dev --tunnel-url https://tunnel-url:3000\n```\n\n## Developer resources\n\n- [Introduction to Shopify apps](https://shopify.dev/apps/getting-started)\n- [App authentication](https://shopify.dev/apps/auth)\n- [Shopify CLI](https://shopify.dev/apps/tools/cli)\n- [Shopify API Library documentation](https://github.com/Shopify/shopify-api-ruby/tree/main/docs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festerified%2Fruby-shopify-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Festerified%2Fruby-shopify-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festerified%2Fruby-shopify-app/lists"}