From 232021939303c8857c3d2345b40bc5cd22dd289b Mon Sep 17 00:00:00 2001 From: Jacob Erickson Date: Tue, 9 Jan 2024 16:59:44 -0500 Subject: [PATCH] Update readme, add workflow --- .github/workflows/sync-upstream.yml | 39 ++++ README.md | 267 +--------------------------- 2 files changed, 44 insertions(+), 262 deletions(-) create mode 100644 .github/workflows/sync-upstream.yml diff --git a/.github/workflows/sync-upstream.yml b/.github/workflows/sync-upstream.yml new file mode 100644 index 00000000..c1fb955b --- /dev/null +++ b/.github/workflows/sync-upstream.yml @@ -0,0 +1,39 @@ +name: Sync fork with upstream branch + +on: + schedule: + - cron: '0 7 * * 1,4' + # scheduled at 07:00 every Monday and Thursday + + workflow_dispatch: + +jobs: + sync_latest_from_upstream: + runs-on: ubuntu-latest + name: Sync latest commits from upstream repo + + steps: + - name: Checkout target repo + uses: actions/checkout@v3 + with: + ref: main + + - name: Sync upstream changes + id: sync + uses: aormsby/Fork-Sync-With-Upstream-action@v3.4 + with: + target_sync_branch: main + target_repo_token: ${{ secrets.GITHUB_TOKEN }} + upstream_sync_branch: main + upstream_sync_repo: Shopify/shopify-app-template-remix + + - name: New commits found + if: steps.sync.outputs.has_new_commits == 'true' + run: echo "New commits were found to sync." + + - name: No new commits + if: steps.sync.outputs.has_new_commits == 'false' + run: echo "There were no new commits." + + - name: Show value of 'has_new_commits' + run: echo ${{ steps.sync.outputs.has_new_commits }} \ No newline at end of file diff --git a/README.md b/README.md index 22850e15..f26268ab 100644 --- a/README.md +++ b/README.md @@ -1,265 +1,8 @@ -# Shopify App Template - Remix +# Shopify Credit Card Payments App Template - Remix [Typescript] -This is a template for building a [Shopify app](https://shopify.dev/docs/apps/getting-started) using the [Remix](https://remix.run) framework. +The `main` branch in this repository contains no changes to the source [shopify-app-template-remix](https://github.com/Shopify/shopify-app-template-remix). The typescript template for payments apps is a work in progress. -Rather than cloning this repo, you can use your preferred package manager and the Shopify CLI with [these steps](https://shopify.dev/docs/apps/getting-started/create). +Consider using one of the following branches instead: -Visit the [`shopify.dev` documentation](https://shopify.dev/docs/api/shopify-app-remix) for more details on the Remix app package. - -## Quick start - -### Prerequisites - -1. You must [download and install Node.js](https://nodejs.org/en/download/) if you don't already have it. -2. You must [create a Shopify partner account](https://partners.shopify.com/signup) if you don’t have one. -3. 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). - -### Setup - -If you used the CLI to create the template, you can skip this section. - -Using yarn: - -```shell -yarn install -``` - -Using npm: - -```shell -npm install -``` - -Using pnpm: - -```shell -pnpm install -``` - -### Local Development - -Using yarn: - -```shell -yarn dev -``` - -Using npm: - -```shell -npm run dev -``` - -Using pnpm: - -```shell -pnpm run dev -``` - -Press P to open the URL to your app. Once you click install, you can start development. - -Local development is powered by [the Shopify CLI](https://shopify.dev/docs/apps/tools/cli). It logs into your partners account, connects to an app, provides environment variables, updates remote config, creates a tunnel and provides commands to generate extensions. - -### Authenticating and querying data - -To authenticate and query data you can use the `shopify` const that is exported from `/app/shopify.server.js`: - -```js -export async function loader({ request }) { - const { admin } = await shopify.authenticate.admin(request); - - const response = await admin.graphql(` - { - products(first: 25) { - nodes { - title - description - } - } - }`); - - const { - data: { - products: { nodes }, - }, - } = await response.json(); - - return json(nodes); -} -``` - -This template come preconfigured with examples of: - -1. Setting up your Shopify app in [/app/shopify.server.js](https://github.com/Shopify/shopify-app-template-remix/blob/main/app/shopify.server.js) -2. Querying data using Graphql. Please see: [/app/routes/app.\_index.jsx](https://github.com/Shopify/shopify-app-template-remix/blob/main/app/routes/app._index.jsx). -3. Responding to mandatory webhooks in [/app/routes/webhooks.jsx](https://github.com/Shopify/shopify-app-template-remix/blob/main/app/routes/webhooks.jsx) - -Please read the [documentation for @shopify/shopify-app-remix](https://www.npmjs.com/package/@shopify/shopify-app-remix#authenticating-admin-requests) to understand what other API's are available. - -## Deployment - -### Application Storage - -This template uses [Prisma](https://www.prisma.io/) to store session data, by default using an [SQLite](https://www.sqlite.org/index.html) database. -The database is defined as a Prisma schema in `prisma/schema.prisma`. - -This use of SQLite works in production if your app runs as a single instance. -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. -Here’s a short list of databases providers that provide a free tier to get started: - -| Database | Type | Hosters | -| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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) | -| 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) | -| Redis | Key-value | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-redis), [Amazon MemoryDB](https://aws.amazon.com/memorydb/) | -| MongoDB | NoSQL / Document | [Digital Ocean](https://www.digitalocean.com/try/managed-databases-mongodb), [MongoDB Atlas](https://www.mongodb.com/atlas/database) | - -To use one of these, you can use a different [datasource provider](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#datasource) in your `schema.prisma` file, or a different [SessionStorage adapter package](https://github.com/Shopify/shopify-api-js/tree/main/docs/guides/session-storage.md). - -### Build - -Remix handles building the app for you, by running the command below with the package manager of your choice: - -Using yarn: - -```shell -yarn build -``` - -Using npm: - -```shell -npm run build -``` - -Using pnpm: - -```shell -pnpm run build -``` - -## Hosting - -When 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/). - -When 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`. - -## Gotchas / Troubleshooting - -### Database tables don't exist - -If you get this error: - -``` -The table `main.Session` does not exist in the current database. -``` - -You need to create the database for Prisma. Run the `setup` script in `package.json` using your preferred package manager. - -### Navigating/redirecting breaks an embedded app - -Embedded Shopify apps must maintain the user session, which can be tricky inside an iFrame. To avoid issues: - -1. Use `Link` from `@remix-run/react` or `@shopify/polaris`. Do not use ``. -2. Use the `redirect` helper returned from `authenticate.admin`. Do not use `redirect` from `@remix-run/node` -3. Use `useSubmit` or `
` from `@remix-run/react`. Do not use a lowercase ``. - -This only applies if you app is embedded, which it will be by default. - -### Non Embedded - -Shopify apps are best when they are embedded into the Shopify Admin. This template is configured that way. If you have a reason to not embed your please make 2 changes: - -1. Change the `isEmbeddedApp` prop to false for the `AppProvider` in `/app/routes/app.jsx` -2. Remove any use of App Bridge APIs (`window.shopify`) from your code -3. Update the config for shopifyApp in `app/shopify.server.js`. Pass `isEmbeddedApp: false` - -### OAuth goes into a loop when I change my app's scopes - -If you change your app's scopes and authentication goes into a loop and fails with a message from Shopify that it tried too many times, you might have forgotten to update your scopes with Shopify. -To do that, you can run the `config push` CLI command. - -Using yarn: - -```shell -yarn shopify app config push -``` - -Using npm: - -```shell -npm run shopify app config push -``` - -Using pnpm: - -```shell -pnpm run shopify app config push -``` - -### My webhook subscriptions aren't being updated - -This template registers webhooks after OAuth completes, usng the `afterAuth` hook when calling `shopifyApp`. -The package calls that hook in 2 scenarios: -- After installing the app -- When an access token expires - -During normal development, the app won't need to re-authenticate most of the time, so the subscriptions aren't updated. - -To force your app to update the subscriptions, you can uninstall and reinstall it in your development store. -That will force the OAuth process and call the `afterAuth` hook. - -### Admin created webhook failing HMAC validation - -Webhooks subscriptions created in the [Shopify admin](https://help.shopify.com/en/manual/orders/notifications/webhooks) will fail HMAC validation. This is because the webhook payload is not signed with your app's secret key. - -Create [webhook subscriptions]((https://shopify.dev/docs/api/shopify-app-remix/v1/guide-webhooks)) using the `shopifyApp` object instead. - -Test your webhooks with the [Shopify CLI](https://shopify.dev/docs/apps/tools/cli/commands#webhook-trigger) or by triggering events manually in the Shopify admin(e.g. Updating the product title to trigger a `PRODUCTS_UPDATE`). - -### Incorrect GraphQL Hints - -By default the [graphql.vscode-graphql](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) extension for VS Code will assume that GraphQL queries or mutations are for the [Shopify Admin API](https://shopify.dev/docs/api/admin). This is a sensible default, but it may not be true if: - -1. You use another Shopify API such as the storefront API. -2. You use a third party GraphQL API. - -in this situation, please update the [.graphqlrc.js](https://github.com/Shopify/shopify-app-template-remix/blob/main/.graphqlrc.js) config. - -## Benefits - -Shopify apps are built on a variety of Shopify tools to create a great merchant experience. - - - - -The Remix app template comes with the following out-of-the-box functionality: - -- [OAuth](https://github.com/Shopify/shopify-app-js/tree/main/packages/shopify-app-remix#authenticating-admin-requests): Installing the app and granting permissions -- [GraphQL Admin API](https://github.com/Shopify/shopify-app-js/tree/main/packages/shopify-app-remix#using-the-shopify-admin-graphql-api): Querying or mutating Shopify admin data -- [REST Admin API](https://github.com/Shopify/shopify-app-js/tree/main/packages/shopify-app-remix#using-the-shopify-admin-rest-api): Resource classes to interact with the API -- [Webhooks](https://github.com/Shopify/shopify-app-js/tree/main/packages/shopify-app-remix#authenticating-webhook-requests): Callbacks sent by Shopify when certain events occur -- [AppBridge](https://shopify.dev/docs/api/app-bridge): This template uses the next generation of the Shopify App Bridge library which works in unison with previous versions. -- [Polaris](https://polaris.shopify.com/): Design system that enables apps to create Shopify-like experiences - -## Tech Stack - -This template uses [Remix](https://remix.run). The following Shopify tools are also included to ease app development: - -- [Shopify App Remix](https://shopify.dev/docs/api/shopify-app-remix) provides authentication and methods for interacting with Shopify APIs. -- [Shopify App Bridge](https://shopify.dev/docs/apps/tools/app-bridge) allows your app to seamlessly integrate your app within Shopify's Admin. -- [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. -- [Webhooks](https://github.com/Shopify/shopify-app-js/tree/main/packages/shopify-app-remix#authenticating-webhook-requests): Callbacks sent by Shopify when certain events occur -- [Polaris](https://polaris.shopify.com/): Design system that enables apps to create Shopify-like experiences - -## Resources - -- [Remix Docs](https://remix.run/docs/en/v1) -- [Shopify App Remix](https://shopify.dev/docs/api/shopify-app-remix) -- [Introduction to Shopify apps](https://shopify.dev/docs/apps/getting-started) -- [App authentication](https://shopify.dev/docs/apps/auth) -- [Shopify CLI](https://shopify.dev/docs/apps/tools/cli) -- [App extensions](https://shopify.dev/docs/apps/app-extensions/list) -- [Shopify Functions](https://shopify.dev/docs/api/functions) -- [Getting started with internationalizing your app](https://shopify.dev/docs/apps/best-practices/internationalization/getting-started) +- [`javascript`](https://github.com/Shopify/example-app--credit-card-payments-app-template--remix/tree/javascript): Contains a credit card payments app template built with Javascript. +- [`docs`](https://github.com/Shopify/example-app--credit-card-payments-app-template--remix/tree/docs): Based on `javascript`, includes tags for documentation.