Universal React+GraphQL starter kit: React 16, Apollo 2, Webpack 4, Styled Components, React Router 4, PostCSS, SSR
Clone or download
Latest commit f79f4c0 Aug 23, 2018
Failed to load latest commit information.
.vscode 3.1.0 Aug 3, 2018
src fixes CSS loading when SASS/LESS/PostCSS not used Aug 23, 2018
types 3.0.0 Aug 3, 2018
.dockerignore 3.0.0 Aug 3, 2018
.gitignore 3.0.0 Aug 3, 2018
CHANGELOG 3.0.0 Aug 3, 2018
Dockerfile 3.2.0 Aug 19, 2018
LICENSE 3.0.0 Aug 3, 2018
README.md Update README.md Aug 23, 2018
index.ts 3.0.0 Aug 3, 2018
package-lock.json package lock Aug 19, 2018
package.json 3.2.0 Aug 19, 2018
tsconfig.json 3.0.0 Aug 3, 2018
tslint.json 3.1.0 Aug 3, 2018



license Twitter Follow

Universal front-end React + GraphQL starter kit, written in Typescript.



Front-end stack

Server-side rendering

  • Built-in Koa 2 web server, with async/await routing.
  • Full route-aware server-side rendering (SSR) of initial HTML.
  • Universal building - both browser + Node.js web server compile down to static files, for fast server re-spawning.
  • Per-request GraphQL local state. Store state is dehydrated via SSR, and rehydrated automatically on the client.
  • Full page React via built-in SSR component - every byte of your HTML is React.
  • SSR in both development and production, even with hot-code reload.


  • Hot code reloading; zero refresh, real-time updates in development.
  • Development web server that automatically sends patches on code changes, and restarts the built-in Web server for SSR renders that reflect what you'd see in production.

Code optimisation

  • Webpack v4, with tree shaking -- dead code paths are automatically eliminated.
  • Asynchronous code loading when import()'ing inside a function.
  • Aggressive code minification.
  • CSS code is combined, minified and optimised automatically - even if you use SASS, LESS and CSS together!


  • Styled Components, for writing CSS styles inline and generating the minimal CSS required to properly render your components. Full type inference on themes, too.
  • PostCSS v7 with next-gen CSS and automatic vendor prefixing when importing .css, .scss or .less files.
  • SASS and LESS support (also parsed through PostCSS.)
  • Automatic vendor prefixing - write modern CSS, and let the compiler take care of browser compatibility.
  • Mix and match SASS, LESS and regular CSS - without conflicts!
  • CSS modules - your classes are hashed automatically, to avoid namespace conflicts.
  • Compatible with Foundation, Bootstrap, Material and more. Simply configure via a .global.(css|scss|less) import to preserve class names.


  • Production bundling via npm run production, that generates optimised server and client code.
  • Static compression using the Gzip and Brotli algorithms for the serving of static assets as pre-compressed .gz and .br files (your entire app's main.js.bz - including all dependencies - goes from 346kb -> 89kb!)
  • Automatic HTTP hardening against common attack vectors via Koa Helmet (highly configurable)

Developer support

  • Written in Typescript with full type support, out the box (all external @types/* packages installed)
  • Heavily documented code

Quick start

Grab and unpack the latest version, install all dependencies, and start a server:

wget -qO- https://github.com/leebenson/reactql/archive/3.2.1.tar.gz | tar xvz
cd reactql-3.2.1
npm i
npm start

Your development server is now running on http://localhost:3000

Development mode

Development mode offers a few useful features:

  • Hot code reloading. Make a change anywhere in your code base (outside of the Webpack config), and changes will be pushed down the browser automatically - without page reloads. This happens for React, Styled Components, SASS - pretty much anything.

  • Full source maps for Javascript and CSS

  • Full server-side rendering, with automatic Koa web server restarting on code changes. This ensures the initial HTML render will always reflect your latest code changes

To get started, simply run:

npm start

A server will be started on http://localhost:3000

Production mode

In production mode, the following happens:

  • All assets are optimised and minified. Javascript, CSS, images, are all compiled down to static files that will appear in dist.

  • Assets are also compressed into .gz (Gzip) and .br (Brotli) versions, which are served automatically to all capable browsers.

  • If files have been generated in a previous run, they will be re-used on subsequent runs. This ensures really fast server start-up times after the initial build.

To build and run for production, use:

npm run production

Files will be generated in ./dist, and a server will also be spawned at http://localhost:3000

Clean the cached production build with npm run clean, or run npm run clean-production to both clean and re-run the production build, as needed.

Build mode

If you only want to build assets and not actually run the server, use:

npm run build

This is used in the Dockerfile, for example, to pre-compile assets and ensure faster start-up times when spawning a new container.

Project layout

The important stuff is in src.

Here's a quick run-through of each sub-folder and what you'll find in it:

  • src/components - React components. Follow the import flow at root.tsx to figure out the component render chain. I've included an example component that shows off some Apollo GraphQL features, including incrementing a local counter and pulling top news stories from Hacker News (a live GraphQL server endpoint.)

  • src/data - Data used throughout your app. You'll find routes.ts, which defines your React Router routes (currently, just the home page -- but you can easily extend this.)

  • src/entry - The client and server entry points, which call on src/components/root.tsx to isomorphically render the React chain in both environments.

  • src/global - A good place for anything that's used through your entire app, like global styles. I've started you off with a styles.ts that sets globally inlined Styled Components CSS, as well as pulls in a global .scss file -- to show you how both types of CSS work.

  • src/graphql - GraphQL initialisation goes here. There's an apollo.ts which builds a universal Apollo Client and enables local state, and state.ts which sets up default state (automatically rehydrated on the client) and some mutation handlers, for incrementing a local counter.

  • src/lib - Library functions to handle hot-code reloading, finding the right main.js / main.css in production (which is automatically hashed for versioning), Webpack stats and Styled Components.

  • src/mutations - Your GraphQL mutations. Out-the-box, you'll find the query to increment the local state counter.

  • src/queries - Your GraphQL queries. There are two by default - one that grabs the local counter state, another that pulls the top stories from Hacker News to display in the example component.

  • src/runner - Development and production runners that spawn the Webpack build process in each environment.

  • src/themes - A sample interface type for defining a Styled Components theme, and a default theme that's used in the example component to add an orange hover to Hacker News links.

  • src/views - View components that fall outside of the usual React component chain, for use on the server. In here, ssr.tsx takes care of rendering the root HTML that's sent down the wire to the client. Note this is also a React component - your whole app will render as React!

  • src/webpack - The Webpack 4 configuration files that do the heavy lifting to transform our Typescript code, images and CSS into optimised and minified assets that wind up in the dist folder at the root. Handles both the client and server environments.

You'll also find some other useful goodies in the root...

  • types - Some basic types that allow you to import fonts, images, CSS/SASS/LESS files, and allow use of the global SERVER boolean in your IDE.

  • Typescript configuration via tsconfig.json and tslint.json

  • A sample Dockerfile for quickly deploying your code base to production.

Follow @reactql for updates

Get the latest updates by following us on Twitter: https://twitter.com/reactql

Twitter Follow

New to GraphQL? Need help?


Join the ReactQL slack channel here.

Watch my free 45 minute YouTube video, for a live coding walk-through of putting together a GraphQL server with a database. Learn how to write queries, mutations and handle nested/related data.

Hire me

I'm a full-stack developer with 20+ years experience. As well as 9 years hands-on dev with Node.js, I'm fluent in Python, Go, SQL and NoSQL. I specialise in building robust, scalable products from scratch, and helping you deploy fast.

If you're looking for a senior developer who can help you get your product out the door quickly, reach me at lee@leebenson.com. I'm occasionally available to take on remote contracts when I'm not working on my own projects.