{"id":13515259,"url":"https://github.com/Shopify/shopify-app-template-node","last_synced_at":"2025-03-31T04:36:45.133Z","repository":{"id":37072535,"uuid":"148527447","full_name":"Shopify/shopify-app-template-node","owner":"Shopify","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-29T14:56:28.000Z","size":7175,"stargazers_count":929,"open_issues_count":43,"forks_count":406,"subscribers_count":386,"default_branch":"main","last_synced_at":"2025-03-28T03:41:19.893Z","etag":null,"topics":["javascript","react","shopify","shopify-app"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shopify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-12T18:57:12.000Z","updated_at":"2025-03-25T12:14:55.000Z","dependencies_parsed_at":"2024-08-21T17:22:22.677Z","dependency_job_id":"470398d5-aa74-4eed-9523-16111c0da23b","html_url":"https://github.com/Shopify/shopify-app-template-node","commit_stats":null,"previous_names":["shopify/shopify-app-node"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshopify-app-template-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshopify-app-template-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshopify-app-template-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshopify-app-template-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shopify","download_url":"https://codeload.github.com/Shopify/shopify-app-template-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245972676,"owners_count":20702721,"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":["javascript","react","shopify","shopify-app"],"created_at":"2024-08-01T05:01:08.495Z","updated_at":"2025-03-31T04:36:40.077Z","avatar_url":"https://github.com/Shopify.png","language":"JavaScript","readme":"# Shopify App Template for Node\n\nThis is a template for building a [Shopify app](https://shopify.dev/docs/apps/getting-started) using Node 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/docs/apps/getting-started/create) tutorial in our developer documentation will guide you through creating a Shopify app using this template.\n\nThe Node 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- [Express](https://expressjs.com/) 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- [`i18next`](https://www.i18next.com/) and related libraries are used to internationalize the frontend.\n  - [`react-i18next`](https://react.i18next.com/) is used for React-specific i18n functionality.\n  - [`i18next-resources-to-backend`](https://github.com/i18next/i18next-resources-to-backend) is used to dynamically load app translations.\n  - [`@formatjs/intl-localematcher`](https://formatjs.io/docs/polyfills/intl-localematcher/) is used to match the user locale with supported app locales.\n  - [`@formatjs/intl-locale`](https://formatjs.io/docs/polyfills/intl-locale) is used as a polyfill for [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) if necessary.\n  - [`@formatjs/intl-pluralrules`](https://formatjs.io/docs/polyfills/intl-pluralrules) is used as a polyfill for [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) if necessary.\n\nThe following Shopify tools complement these third-party tools to ease app development:\n\n- [Shopify API library](https://github.com/Shopify/shopify-node-api) adds OAuth to the Express backend. This lets users install the app and grant scope permissions.\n- [App Bridge React](https://shopify.dev/docs/apps/tools/app-bridge/getting-started/using-react) adds 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- [`@shopify/i18next-shopify`](https://github.com/Shopify/i18next-shopify) is a plugin for [`i18next`](https://www.i18next.com/) that allows translation files to follow the same JSON schema used by Shopify [app extensions](https://shopify.dev/docs/apps/checkout/best-practices/localizing-ui-extensions#how-it-works) and [themes](https://shopify.dev/docs/themes/architecture/locales/storefront-locale-files#usage).\n\n## Getting started\n\n### Requirements\n\n1. You must [download and install Node.js](https://nodejs.org/en/download/) if you don't already have it.\n1. You must [create a Shopify partner account](https://partners.shopify.com/signup) if you don’t have one.\n1. You must create a store for testing if you don't have one, either a [development store](https://help.shopify.com/en/partners/dashboard/development-stores#create-a-development-store) or a [Shopify Plus sandbox store](https://help.shopify.com/en/partners/dashboard/managing-stores/plus-sandbox-store).\n\n### Installing the template\n\nThis template can be installed using your preferred package manager:\n\nUsing yarn:\n\n```shell\nyarn create @shopify/app --template=node\n```\n\nUsing npm:\n\n```shell\nnpm init @shopify/app@latest -- --template=node\n```\n\nUsing pnpm:\n\n```shell\npnpm create @shopify/app@latest --template=node\n```\n\nThis will clone the template and install the required dependencies.\n\n#### Local Development\n\n[The Shopify CLI](https://shopify.dev/docs/apps/tools/cli) connects to an app in your Partners dashboard. It provides environment variables, runs commands in parallel, and updates application URLs for easier development.\n\nYou can develop locally using your preferred package manager. Run 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 [SQLite](https://www.sqlite.org/index.html) to store session data. The database is a file called `database.sqlite` which is automatically created in the root. This use of SQLite works in production if your app runs as a single instance.\n\nThe 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. Here’s a short list of databases providers that provide a free tier to get started:\n\n| Database   | Type             | Hosters                                                                                                                                                                                                                               |\n| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| MySQL      | SQL              | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-mysql), [Planet Scale](https://planetscale.com/), [Amazon Aurora](https://aws.amazon.com/rds/aurora/), [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql) |\n| PostgreSQL | SQL              | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-postgresql), [Amazon Aurora](https://aws.amazon.com/rds/aurora/), [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres)                                   |\n| Redis      | Key-value        | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-redis), [Amazon MemoryDB](https://aws.amazon.com/memorydb/)                                                                                                        |\n| MongoDB    | NoSQL / Document | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-mongodb), [MongoDB Atlas](https://www.mongodb.com/atlas/database)                                                                                                  |\n\nTo use one of these, you need to change your session storage configuration. To help, here’s a list of [SessionStorage adapter packages](https://github.com/Shopify/shopify-api-js/blob/main/packages/shopify-api/docs/guides/session-storage.md).\n\n### Build\n\nThe frontend is a single page app. It requires the `SHOPIFY_API_KEY`, which you can find on the page for your app in your partners dashboard. Paste your app’s key in the command for the package manager of your choice:\n\nUsing yarn:\n\n```shell\ncd web/frontend/ \u0026\u0026 SHOPIFY_API_KEY=REPLACE_ME yarn build\n```\n\nUsing npm:\n\n```shell\ncd web/frontend/ \u0026\u0026 SHOPIFY_API_KEY=REPLACE_ME npm run build\n```\n\nUsing pnpm:\n\n```shell\ncd web/frontend/ \u0026\u0026 SHOPIFY_API_KEY=REPLACE_ME pnpm run build\n```\n\nYou do not need to build the backend.\n\n## Hosting\n\nWhen you're ready to set up your app in production, you can follow [our deployment documentation](https://shopify.dev/docs/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/docs/apps/deployment/web#set-env-vars), you also need to set the variable `NODE_ENV=production`.\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```text\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\nOut of the logs produced by cloudflare you will notice a https URL where the domain ends with `trycloudflare.com`. This is your tunnel URL. You need to copy this URL as you will need it in the next step.\n\n```shell\n2022-11-11T19:57:55Z INF Requesting new quick Tunnel on trycloudflare.com...\n2022-11-11T19:57:58Z INF +--------------------------------------------------------------------------------------------+\n2022-11-11T19:57:58Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |\n2022-11-11T19:57:58Z INF |  https://randomly-generated-hostname.trycloudflare.com                                     |\n2022-11-11T19:57:58Z INF +--------------------------------------------------------------------------------------------+\n```\n\nBelow you would replace `randomly-generated-hostname` with what you have copied from the terminal. In a different terminal window, navigate to your app's root and with the URL from above you would call:\n\n```shell\n# Using yarn\nyarn dev --tunnel-url https://randomly-generated-hostname.trycloudflare.com:3000\n# or using npm\nnpm run dev --tunnel-url https://randomly-generated-hostname.trycloudflare.com:3000\n# or using pnpm\npnpm dev --tunnel-url https://randomly-generated-hostname.trycloudflare.com:3000\n```\n\n## Developer resources\n\n- [Introduction to Shopify apps](https://shopify.dev/docs/apps/getting-started)\n- [App authentication](https://shopify.dev/docs/apps/auth)\n- [Shopify CLI](https://shopify.dev/docs/apps/tools/cli)\n- [Shopify API Library documentation](https://github.com/Shopify/shopify-api-js#readme)\n- [Getting started with internationalizing your app](https://shopify.dev/docs/apps/best-practices/internationalization/getting-started)\n  - [i18next](https://www.i18next.com/)\n    - [Configuration options](https://www.i18next.com/overview/configuration-options)\n  - [react-i18next](https://react.i18next.com/)\n    - [`useTranslation` hook](https://react.i18next.com/latest/usetranslation-hook)\n    - [`Trans` component usage with components array](https://react.i18next.com/latest/trans-component#alternative-usage-components-array)\n  - [i18n-ally VS Code extension](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally)\n","funding_links":[],"categories":["JavaScript","Examples","示例","Example Apps"],"sub_categories":["JavaScript Examples","JavaScript 示例"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fshopify-app-template-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShopify%2Fshopify-app-template-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fshopify-app-template-node/lists"}