Apollo Universal Starter Kit with back-end & front-end Hot Code Reload

Apollo Universal Starter Kit is a SEO friendly boilerplate for Universal web app development built on top of Apollo, GraphQL, React, Redux, Express with SQL storage support and Twitter Bootstrap integration. Hot Code Reload of back end & front end using Webpack and Hot Module Replacement to reflect your changes instantly and help you stay productive.

Hot Code Reload demo

Getting Started

1. Clone starter kit locally.

git clone https://github.com/sysgears/apollo-fullstack-starter-kit.git
cd apollo-fullstack-starter-kit

2. Install dependencies.

npm i

or

yarn

3. Seed sample database data.

npm run seed

or

yarn seed

4. Run starter kit in development mode.

npm run watch

or

yarn watch

6. Point your browser to http://localhost:3000
7. Change any app code and see the changes applied immediately!
8. Open app in multiple tabs, try to increase counter or add a new post/comment in one tab and then switch to another tab. You will see that counter value and post/comment are updated there as well, because the application is live updated via subscriptions.

Deployment to Production

Deploying to Linux running Node.js

1. Clone starter kit locally.

git clone https://github.com/sysgears/apollo-fullstack-starter-kit.git
cd apollo-fullstack-starter-kit

2. Install dependencies.

npm i

or

yarn

3. Seed production database data.

npm run seed --prod

or

NODE_ENV=production yarn seed

5. Compile project.

npm run build

or

yarn build

6. Run project in production mode.

node build/server

or

npm start

or

yarn start

Deploying to Heroku

1. Add your app to Heroku
2. Allow Heroku to install build time dependencies from the devDependencies in package.json: Settings -> Config Variables -> Add, KEY: NPM_CONFIG_PRODUCTION, VALUE: false.
3. Deploy your app on Heroku

Heroku Demo

You can see latest version of this app deployed to Heroku here: https://apollo-fullstack-starter-kit.herokuapp.com

Additional scripts

While developing, you will probably rely mostly on npm run watch or yarn watch; however, there are additional scripts at your disposal:

npm run or yarn <script>	Description
watch	Run your app in develooment mode and watch your changes. Hot code reload will be enabled in development.
start	Run your app in production mode.
build	Compiles the application to the build folder.
tests	Runs unit tests with Mocha.
tests:watch	Runs unit tests with Mocha and watches for changes automatically to re-run tests.
test	Runs unit tests with Mocha and check for lint errors
lint	Check for lint errors and runs for all .js and .jsx files.
seed	Seed sample database using SQLite. Use --prod flag to run in "production" mode.
migrate	Migrate the sample database
rollback	Rollback the sample database to previous state.

Project Structure

The project structure presented in this boilerplate is fractal, where functionality is grouped primarily by feature rather than file type. This structure is only meant to serve as a guide, it is by no means prescriptive. That said, it aims to represent generally accepted guidelines and patterns for building scalable applications.

.
├── src                      # Application source code
│   ├── client               # Fractal route for client side code
│   │   ├── app              # Fractal route for common client application code
│   │   └── modules          # Fractal route for client-side application module splitting (components, containers, GraphQL queries, redux reducers)
│   │   └── styles           # Application-wide styles
│   │   └── test-helpers     # Test helper for apollo client tests
│   │   └── index.jsx        # Render client with hot reload
│   ├── common               # Apollo client, redux store and logging
│   └── server               # Fractal route for server side code
│   │   ├── api              # Initialization of GraphQL schema and subscription.
│   │   └── database         # Fractal route for application module splitting
│   │   │   └── migrations   # Database migration script using Knex
│   │   │   └── seeds        # Database seed script using Knex
│   │   └── middleware       # Graphiql, GraphQL express and SSR rendering
│   │   └── modules          # Fractal route for server-side application module splitting (schema definition, resolvers, sql queries)
│   │   └── sql              # Knex connector
│   │   └── test-helpers     # Test helper for apollo server tests
│   │   └── api_server.js    # GraphQL api server set up
│   │   └── index.js         # Render server with hot reload
└── tools                    # All build related files (Webpack)

Features

• Webpack for back end

  This starter kit is different from most of the starter kits out there, because it uses Webpack not only for front end, but for back-end code as well. This enables powerful Webpack features for back-end code, such as conditional compilation, embedding non-js files and CSS stylesheets into the code, hot code reload, etc. To use external backend set serverConfig.url at tools/webpack.app_config.js

• Hot Code Reload for back end and front end

  Hot Code Reload for back end is done using Webpack. When Webpack prepares hot patches on the filesystem, SIGUSR2 signal is sent to Node.js app and embedded Webpack Hot Module Runtime reacts to this signal and applies patches to running modules from filesystem. Hot code reload for front end is using Webpack Dev Server and Hot Module Replacement to apply patches to front-end code. Hot patches for React components are applied on the front end and back end at the same time, so React should not complain about differences in client and server code.

• Webpack DLL vendor bundle generation and updating out of the box

  For all the non-development dependencies of project package.json the Webpack vendor DLL bundle is generated and updated automatically, so that Webpack didn't process vendor libraries on each change to the project, but only when they are actually changed. This boosts speed of cold project start in development mode and speed of hot code reload even if the number of dependencies is huge.

• Server Side Rendering with Apollo Redux Store sync

  On the initial web page request back end fully renders UI and hands off Apollo Redux Store state to front end. Frontend then starts off from there and updates itself on user interactions.

  If you don't need Server Side Rendering, set package.json ssr field to false

• Optimistic UI updates

  This example application uses Apollo optimistic UI updates, that result in immediate UI update on user interaction and then, after data arrives from the server, UI state is finalized.

• GraphQL API

  GraphQL is used as very flexible and much faster API in terms of bandwidth and round-trips, compared to REST. GraphQL requests are batched together automatically by Apollo

• GraphQL subscription example

  GraphQL subscription is utilized to make counter updating in real-time.

• SQL and arbitrary data sources support

  Knex code to access SQLite is included as an example of using arbitrary data source with Apollo and GraphQL. NoSQL storage or any other data source can be used the same way.

  Debug SQL Prints out execuded queries, with respective times in development mode and can be set in package.json by debugSQL field true

• Powerful stylesheets with Hot Reloading

  Twitter Bootstrap in form of SASS stylesheets is used for styling demo application. Application has stylesheet in styles.scss for global styling which is Hot Reloaded on change. React components styling is done by Glamor v3.

• Babel for ES2017 transpiling

• ESLint to enforce proper code style

• React Hot Loader v3 for the sake of completeness this project also supports React Hot Loader v3, but it is turned off. By default this starter kit uses pure Webpack HMR for all hot reloading purposes and we think it covers all practical needs during development and using React Hot Loader v3 in addition to Webpack HMR makes hot reloading less predictable and buggy. To turn React Hot Loader v3 on: set reactHotLoader field of package.json to true.

• PersistGraphQL Webpack Plugin is a tool to gather static GraphQL queries for GraphQL projects and inject them into build. It will make front end and back end aware of static queries used in the project and will only allow these queries for better security and less bandwidth.

• Dataloader for loading comments in post example

• GraphQL Cursor Pagination Example of  Relay-style cursor pagination

• Declarative/dynamic head section, using React Helmet

• Google Analytics integration using React GA

• Full CRUD funcionality with Subscriptions in post example, with ReduxForm

Contributors

Thanks goes to these wonderful people (emoji key):

Victor Vlasenko 💻 🔧 📖 ⚠️ 💬 👀	mitjade 💻 🔧 💬	Dmitry Pavlenko 💻 🔧	Joe 💻 🔧 📖 💬	Gilad Shoham 💻 🔧 💬	Alexander Vetrov 💻 ⚠️	Nikita Pavlov 💻
Yishai Chernovitzky 💻 🔧	Ujjwal 💻 🔧 📖 💬

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Copyright © 2016, 2017 SysGears INC. This source code is licensed under the MIT license.