gem-hunter
Language: TypeScript
Universal React+GraphQL starter kit: React 16, Apollo 2, MobX, Emotion, Webpack 4, GraphQL Code Generator, React Router 4, PostCSS, SSR
Universal front-end React + GraphQL starter kit, written in Typescript.
<style> tag generation that contains only the CSS that needs to be rendered..css/.scss/.less files.<Query> / <Mutation> queries manually<head> section, using react-helmet.subscription query support for real-time data (just set WS_SUBSCRIPTIONS=1 in .env)import()'ing inside a function..css, .scss or .less files..global.(css|scss|less) import to preserve class names.npm run production, that generates optimised server and client code..gz and .br files (your entire app's main.js.bz - including all dependencies - goes from 346kb -> 89kb!)npm run build:static. Don't need server-side rendering? No problem. Easily deploy a client-only SPA to any static web host (Netlify, etc.)@types/* packages installed)Grab and unpack the latest version, install all dependencies, and start a server:
wget -qO- https://github.com/leebenson/reactql/archive/4.5.1.tar.gz | tar xvz
cd reactql-4.5.1
npm i
npm start
Your development server is now running on http://localhost:3000
By default, your GraphQL schema lives in schema/schema.graphql
To create fully Typescript-typed Apollo React HOCs based on your schema, simply put the query in a .graphql anywhere inside the source folder, and run:
npm run gen:graphql
You can then import the query like we do in the HackerNews demo component:
// Query to get top stories from HackerNews import { GetHackerNewsTopStoriesComponent } from "@/graphql";
And use it as follows:
<GetHackerNewsTopStoriesComponent> {({ data, loading, error }) => (...)} </GetHackerNewsTopStoriesComponent>
To get access to the underlying gql-templated query (in case you need it for refetching, etc), in this case it'd be GetHackerNewsTopStoriesDocument.
See GraphQL Code Generator for more details on how it works.
You can also edit codegen.yml in the root to point to a remote schema, or change the file location.
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, Emotion, 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
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.
If you only want to build assets and not actually run the server, use:
npm run build:production
This is used in the Dockerfile, for example, to pre-compile assets and ensure faster start-up times when spawning a new container.
If you're targeting a client-only SPA and hosting statically, you probably don't want to run a Koa web server to handle HTTP requests and render React.
Instead, you can use static mode, which produces the client-side JS, CSS and assets files, along with an index.html for minimal bootstrapping, and dumps them in dist/public.
You can then upload the contents of that folder wherever you like - et voila, you'll have a working client-side Single Page App!
There are two static modes available -- for dev and production:
### Development (hot-code reload)
Just like the full-stack version, dev mode gives you hot code reloading, so changes to your local files will be pushed to the browser.
To activate static dev mode, just run:
npm run dev:static
Your client-side SPA will be online at http://localhost:3000, just like normal.
### Production (static deployment)
To build your client-side files ready for production deployment, run:
npm run build:static
You'll get everything in that 'regular' building provides you with plus a index.html to bootstrap your JS, just without the server parts.
If you want to make changes to the index.html file that's used for static bundling, edit src/views/static.html
Here's a list of all the NPM script commands available out-the-box:
| Command | What it does |
|---|---|
npm run build:production |
Builds production-ready client/server bundles, but doesn't start a server. |
npm run build:static |
Builds production-ready client bundle and index.html; ignores server bundling. |
npm run clean |
Removes the dist folder, and any previously built client/server bundle. |
npm run dev |
Runs a univeral dev server in memory; auto restarts on code changes and uses hot-code reload in the browser. Does not output anything to dist. |
npm run dev:static |
Runs a client-only dev server using [src/views/static.html] as the template; full hot-code reload. Also doesn't output anything to dist. |
npm run production |
Builds and runs a production-ready client/server bundle. If previously built, will re-use cached files automatically (run npm run clean to clear cache.) |
npm run production:clean |
Same as above, but cleans dist first to ensure a fresh re-build. |
npm start |
Shortcut for npm run dev. |
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 and routing. I've included an example component that shows off some Apollo GraphQL and MobX features, including incrementing a local counter and pulling top news stories from Hacker News (a live GraphQL server endpoint.)
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 Emotion CSS, as well as pulls in a global .scss file -- to show you how both types of CSS work.
src/lib - Internal libraries/helpers. There's an apollo.ts which builds a universal Apollo Client. Plus, Koa middleware to handle hot-code reloading in development and some other Webpack helpers.
src/queries - Your GraphQL queries. There's just one by default - for pulling 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/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! - and static.html serves as a template for rendering a client-side SPA. Update it as needed.
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...
.env - Change your GRAPHQL server endpoint, WS_SUBSCRIPTIONS=1 for built-in WebSocket support, HOST if you want to bind the server to something other than localhost, and LOCAL_STORAGE_KEY to set the root key for saving MobX state locally in the client for automatic re-loading in a later session.
.nvmrc - Specify your preferred Node.js version, for use with NVM and used by many continuous deployment tools. Defaults to v12.2.0
codegen.yml - Settings for GraphQL Code Generator (which you can run with npm run gen:graphql to generate types/HOCs based on your GraphQL queries/mutations.)
netlify.toml - Build instructions for fast Netlify deployments. Tip: To quickly deploy a demo ReactQL app, click here.
types - Some basic types that allow you to import fonts, images, CSS/SASS/LESS files, and allow use of the global SERVER boolean and GRAPHQL endpoint data in your IDE.
Typescript configuration via tsconfig.json
A sample multi-build Dockerfile based on Node 11.8 and Alpine, for quickly deploying your code base to production.
Get the latest updates by following us on Twitter: https://twitter.com/reactql
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.
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.