Generator-shopify-react-app NPM

Shopify React App Generator for Yeoman

Yeoman is a scaffolding system for quickly creating many kinds of apps. This Yeoman generator creates a Shopify App using React & Polaris for a GraphQL backend provided by Shopify Serverless Starter Kit. If you don't want to use a Serverless backend you can build your own GraphQL backend using any language/framework if you prefer.

Installing

To use this starter kit you need to install Yeoman. If you don't already have Yeoman installed then run

npm install yo -g

You should then install the Shopify React Starter generator for Yeoman

npm install generator-shopify-react-app

Finally you can generate a new starter app in the current directory by using

yo shopify-react-app

This will prompt you to enter your application name, Shopify API key and GraphQL endpoint. You can also provide parameters on the command line using

yo shopify-react-app --appname "YOUR APP NAME" --shopifyApiKey "YOUR-API-KEY" --graphqlApiUrl "https://YOUR-SITE/graphql"

Dependencies

Once you've generated the app you need to install the dependencies. All of the depencies are in the generated package.json file. You can install them using:

npm install

Configuration

The configuration has moved the webpack/{environment}.config.js. If you were previously using the src/constants.ts file you need to copy your settings into the relevant webpack config file then remove the constants.ts.

If you filled in these correctly when running the generator then you can skip this.

// The key used to store our temporary OAuth token in localStorage
AUTH_TOKEN_KEY: JSON.stringify("authToken"),

// The base URL for our API endpoint
BASE_API_URL: JSON.stringify("YOUR-GRAPHQL-API-ENDPOINT"),

// Set to true to enable an embedded app or false to disable it
ENABLED_EMBEDDED: JSON.stringify(true),

// The key used to store the shop domain in localStorage
SHOP_KEY: JSON.stringify("shop"),

// Your Shopify API Key
SHOPIFY_API_KEY: JSON.stringify("YOUR-SHOPIFY-API-KEY"),

// The key used to store our API authorization token in localStorage
TOKEN_KEY: JSON.stringify("token"),

Development Server

This project uses the webpack-dev-server. You can start it by running the following command from the projects root folder

npm start

Once the development server has started go to https://localhost:5001/login to login. This URL also accepts the shop query string parameter.

Generating schema.ts

You may notice that the type definitions for the GraphQL API endpoint are in a file called src/schema.ts. This file is automatically generated from your GraphQL API endpoint. To update it you need to modify your package.json and replace YOUR-GRAPHQL-API-ENDPOINT with your actual endpoint.

After doing that you can run the following command to rebuild src/schema.ts based off your actual GraphQL API endpoint and the GraphQL queries inside src/graphql.

npm run update:schema

Generating *.(css|less|saas|scss).d.ts files

The *.(css|less|saas|scss).d.ts files for your CSS/Less/SASS files aren't created by the generator. These files are automatically created by Webpack when it builds your application. If you're using VS Code you'll want these so that autocomplete will work in the browser. The easiest solution is to start the development server using npm start. This will build the .d.ts files for you and update them as you make changes to your source files.

Generating favicon's

The favicon's are generated automatically from src/favicon.png during the webpack build by favicons-webpack-plugin. To update your favicon replace this file with a large square PNG and the all of the smaller sizes will automatically be generated for you.

Note The default file is the Growing eCommerce logo. This is a Trade Mark of Growing eCommerce Pty Ltd and MUST be replace by your own logo before you release your application into production.

GraphQL API

If you are building your own GraphQL API it needs to respond to two mutations.

The first mutation is called to begin the Shopify OAuth process. The mutation accepts the shop hostname, a callback URL (where the user is redirected after they have approved installation of the app) and whether the authentication is per user. This is enough information to generate the URL the user should be redirected to when starting the OAuth process.

The mutation needs to return an object with an authUrl that the user will be redirected to and a token that will be stored locally and sent with the mutation called to complete the OAuth process. The token provides state between API calls so the OAuth nonce parameter can be verified.

mutation ShopifyAuthBegin($shop: String!, $callbackUrl: String!, $perUser: Boolean!) {
    shopifyAuthBegin(shop: $shop, callbackUrl: $callbackUrl, perUser: $perUser) {
        authUrl
        token
    }
}`;

After the user has complete OAuth and approved installation of the application they will be redirected to the callbackUrl you provided earlier. This page should call a second mutation to complete the OAuth process. The second mutation also takes two parameters. token is the token returned by the shopifyAuthBegin() mutation called earlier. params is an object containing the code, hmac, shop, state and timestamp parameters that Shopify added to the callback URL.

This mutation should return an object with another token that can be used for future API requests to the GraphQL API. This is different from the token returned by shopifyAuthBegin() and should not be the access token from Shopify.

mutation ShopifyAuthComplete($token: String!, $params: ShopifyAuthCompleteInput!) {
    shopifyAuthComplete(token: $token, params: $params) {
        token
    }
}`;

Expired Token Handling

When the user presents an expired or invalid authorization token the GraphQL API should respond with a HTTP 403 (Forbidden) status code. The application will then automatically redirect the user to /login.

Refreshng Tokens

If the GraphQL API returns a x-new-token header in the response then the client will automatically replace the authorization token stored in localStorage with the new token. This allows the GraphQL API to refresh the token automatically for users. By using this you can keep token lifetimes short while still allowing the users to stay logged in for extended periods providing they are active.

Releases

From version 5.0 this project will follow a new release number schema based on semver.

Major releases 6.0, 7.0, 8.0 etc will become the norm. These releases will include new features, updated dependencies (production and development) and other code changes.
Minor releases 6.x, 7.x, 8.x etc will occur when Shopify releases a point upgrade to Polaris. These releases will only include the updated Polaris. This will allow us to keep Polaris up to date without needing to do major a release.
Bug releases 6.x.y, 7.x.y, 8.x.y etc will be released as required

See the release notes for more information.

Copyright

shopify react polaris typescript graphql webpack yeoman-generator

7 years ago

7 years ago

7 years ago

7 years ago