Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yoMerce/shopify-app-starter
Shopify App Starter using Node.js, React and Shopify Polaris
https://github.com/yoMerce/shopify-app-starter
Last synced: about 2 months ago
JSON representation
Shopify App Starter using Node.js, React and Shopify Polaris
- Host: GitHub
- URL: https://github.com/yoMerce/shopify-app-starter
- Owner: yoMerce
- License: mit
- Created: 2020-09-10T05:02:58.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2022-09-06T06:00:47.000Z (about 2 years ago)
- Last Synced: 2024-04-17T02:46:05.591Z (5 months ago)
- Language: JavaScript
- Homepage:
- Size: 491 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-shopify - Shopify App Starter (Typescript, Mongo, Express, React) - A shopify app starter written in Typescript. It uses Mongodb, Express and React. (Examples / JavaScript Examples)
README
# Shopify App Template - Node
# v1 (Typescript version) is deprecated in favor of Shopify CLI v3 release as part of Shopify Editions. v1 is still available from the tag v1 and release tab.
## This template will now evolve as an opinionated version derived from the new template version available after Shopify Editions release.
This is a template for building a [Shopify app](https://shopify.dev/apps/getting-started) using Node 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](#installing-the-template).
## Benefits
Shopify 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.
The Node 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
This template combines a number of third party open-source tools:
- [Express](https://expressjs.com/) builds the backend.
- [Vitest](https://vitest.dev/) tests the express backend.
- [Vite](https://vitejs.dev/) builds the [React](https://reactjs.org/) frontend.
- [React Router](https://reactrouter.com/) is used for routing. We wrap this with file-based routing.
- [React Query](https://react-query.tanstack.com/) queries the GraphQL Admin API.
The following Shopify tools complement these third-party tools to ease app development:
- [Shopify API library](https://github.com/Shopify/shopify-api-node) adds OAuth to the Express backend. This lets users install the app and grant scope permissions.
- [App Bridge React](https://shopify.dev/tools/app-bridge/react-components) adds authentication to API requests in the frontend and renders components outside of the App’s iFrame.
- [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.
- [Custom hooks](https://github.com/Shopify/shopify-frontend-template-react/tree/main/hooks) make authenticated requests to the GraphQL Admin API.
- [File-based routing](https://github.com/Shopify/shopify-frontend-template-react/blob/main/Routes.jsx) makes creating new pages easier.
## Getting started
### Requirements
1. You must [download and install Node.js](https://nodejs.org/en/download/) if you don't already have it.
1. You must [create a Shopify partner account](https://partners.shopify.com/signup) if you don’t have one.
1. 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.
### Installing the template
This template can be installed using your preferred package manager:
Using yarn:
```shell
yarn create @shopify/app
```
Using npx:
```shell
npm init @shopify/app@latest
```
Using pnpm:
```shell
pnpm create @shopify/app@latest
```
This will clone the template and install the required dependencies.
#### Local Development
[The Shopify CLI](https://shopify.dev/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.
You can develop locally using your preferred package manager. Run one of the following commands from the root of your app.
Using yarn:
```shell
yarn dev
```
Using npm:
```shell
npm run dev
```
Using pnpm:
```shell
pnpm run dev
```
Open the URL generated in your console. Once you grant permission to the app, you can start development.
### Testing backend code
Unit tests exist for the backend. First, build the [frontend](#build) and then run them using your preferred package manager:
Using yarn:
```shell
cd web && yarn test
```
Using npm:
```shell
cd web && npm run test
```
Using pnpm:
```shell
cd web && pnpm run test
```
### Testing frontend code
Unit tests exist for the frontend. Run these using your preferred package manager:
Using yarn:
```shell
cd web/frontend/ && yarn test
```
Using npm:
```shell
cd web/frontend/ && npm run test
```
Using pnpm:
```shell
cd web/frontend/ && pnpm run test
```
## Deployment
### Application Storage
This 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.
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 need to change your session storage configuration. To help, here’s a list of [SessionStorage adapters](https://github.com/Shopify/shopify-api-node/tree/main/src/auth/session/storage).
### Build
The 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:
Using yarn:
```shell
cd web/frontend/ && SHOPIFY_API_KEY=REPLACE_ME yarn build
```
Using npm:
```shell
cd web/frontend/ && SHOPIFY_API_KEY=REPLACE_ME npm run build
```
Using pnpm:
```shell
cd web/frontend/ && SHOPIFY_API_KEY=REPLACE_ME pnpm run build
```
You do not need to build the backend.
## Hosting
The following pages document the basic steps to host and deploy your application to a few popular cloud providers:
- [fly.io](/web/docs/fly-io.md)
- [Heroku](/web/docs/heroku.md)
## 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 happens because of the way HMR websocket requests work, and the way the CLI is set up to tunnel requests through ngrok.
Until we find a permanent solution that enables HMR on Firefox, this template accepts the `SHOPIFY_VITE_HMR_USE_POLLING` env var to replace HMR with polling.
While not as responsive as HMR, the frontend will still refresh itself every few seconds with your changes.
You can export this variable from your shell profile, or set it when running the `dev` command, e.g.:
```shell
# Using yarn
SHOPIFY_VITE_HMR_USE_POLLING=1 yarn dev
# or using npm
SHOPIFY_VITE_HMR_USE_POLLING=1 npm run dev
# or using pnpm
SHOPIFY_VITE_HMR_USE_POLLING=1 pnpm dev
```
### 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 .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](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/run-tunnel/trycloudflare/) works with this template.
To do that, you can [install the `cloudflared` CLI tool](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/), and run:
```shell
# 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:
```shell
# 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
```
## Developer resources
- [Introduction to Shopify apps](https://shopify.dev/apps/getting-started)
- [App authentication](https://shopify.dev/apps/auth)
- [Shopify CLI](https://shopify.dev/apps/tools/cli)
- [Shopify API Library documentation](https://github.com/Shopify/shopify-api-node/tree/main/docs)