react-apollo-koa-example

An example web app using React, Apollo (GraphQL), Koa v.2.

This project was generated by create-react-app and is not ejected. Some settings are overwritten on runtime though.

passport branch uses Passport to integrate authentication with social services such as Google+, Facebook, etc., whereas master branch uses simple-oauth2 to authenticate with GitHub.

Setup

Install Node.js and Yarn.

Install required packages.

% yarn

Copy .env.default to .env and edit it to change server-side settings.

Copy src/config-default.json to src/config.json and edit it to change client-side settings.

Usage

Launch the API server:

% yarn run server

Launch the development web server which serves the static client-side files:

% yarn start

Open the URL (default: http://localhost:3000) in your browser.

Frameworks/Libraries

Client-side

• React
• Redux
• react-router and react-router-redux (URL routes management)
• redux-auth-wrapper and simple-oauth2 (Authentication)
• redux-logic with RxJS (Async logic management)
• react-app-rewired (Customizing create-react-app w/o ejection)
• Apollo (GraphQL)
• Semantic-UI-React (CSS framework)
• React Storybook and StoryShots (UI dev and test)

The application code was generated by create-react-app.

See package.json for more information.

Server-side (the API server)

• Koa v.2
• Apollo (GraphQL)

See package.json for more information.

The API server does not use DB and stores data on memory. All changes will be cleared when you stop the server.

Tests

• Jest
• Nightmare (Browser automation)

Repo and code management

• Husky and lint-staged (Git hooks)
• ESLint with eslint-config-airbnb and our custom rules (JavaScript lint)
• Flow and flow-typed (JavaScript type check)
• prettier-eslint (JavaScript format)
• stylelint with stylelint-config-standard (CSS lint)
• stylefmt (CSS format)

GraphQL/Apollo

Persisted Queries

GraphQL querires, mutations and subscriptions are defined in src/graphql as .graphql files. They can be used as persisted queries.

You can enable persisted queries by modifying config.json.

{
    "persistedQueries": true
}

You need to generate extracted_queries.json by executing this.

% yarn run persistgraphql

Read the following article to know about persisted queries.

• Persisted GraphQL Queries with Apollo Client

Subscriptions

This example project uses subscriptions. Select "GraphQL Subscription" tab in the header to see it.

Read the following article to know about subscriptions.

• A proposal for GraphQL subscriptions

Authentication

JWT access token and refresh token are used to authenticate a client.

• Access token
  • Expires in 2 hours (default)
• Refresh token
  • Expires in 60 days (default)
  • It is used only for refreshing the access token

The access token is automatically refreshed by WebClient and Apollo client (including GraphQL subscription).

When the refresh token is expired, the user will be automatically signed out.

The WebSocket connection will also be authenticated with a JWT access token. It will be reconnected on signing in/out to do the authentication. There are two types of connection, authenticated and unauthenticated.

You can set the expiration on server-side by editing .env file.

e.g.:

ACCESS_TOKEN_EXPIRES_IN=10s
REFRESH_TOKEN_EXPIRES_IN=2h

You need to sign out and sign in again to apply the new expiration.

It is also possible to set them in client-side localStorage if the server is running on debugging mode.

Set devHeaders as the following (JSON encoded string):

{ "X-ACCESS-TOKEN-EXPIRES-IN": "10s", "X-REFRESH-TOKEN-EXPIRES-IN": "2h" }

Setting devHeaders is useful for testing. See auth_token_test.js.

Storybook

This project uses React Storybook. to develop and check presentational components.

Launch the Storybook server:

% yarn run storybook

StoryShots is also used to enable snapshot tests. When you modify a component and the render result is changed, Jest reports an error. If the shown result is intended, press u to update the snapshot file.

Code Organization

Redux actions, reducers and logic are managed by Ducks rules in src/ducks directory.

Tests are stored in __tests__ directories under each component.

Git Hooks

Git hooks are managed by Husky. When you run yarn in this repo, Git hooks will be automatically created.

If you have a problem, you can create them manually.

% node node_modules/husky/bin/install.js

Our Git hooks are defined in package.json.