Gatsby Starter Collaborative App

A Gatsby starter to create a feature-rich Gatsby progressive web app which supports authentication, session management, and collaborative editing

TL;DR

# Install in repository root, it will automatically install the client & the server
npm ci

# For OSX, install MongoDB if you don't have
# For Linux, see https://docs.mongodb.com/manual/administration/install-on-linux/
brew install mongodb

# Start client and server
npm run dev

# See ./client for the Gatsby app
# See ./server for the ShareDB API

Table of contents

• The app
  • Performance
• Setup
  • Requirements
  • Installation
• Developing
  • Structure
• Set up your own app
  • Cleanup
  • Deployment setup
• Technology Stack
  • Open Source Projects
  • Services
  • Code origin
• Mentionable dependencies
• Contributing

The app

Let us introduce to you: ⏱ Clicker

Clicker is a very simple app where users can list, view, press and create Clickers. A Clicker is a simple button which counts +1 when it was clicked. The Clicker count is updated in real time to all clients. Users can even create private Clickers which are only visible to them.

While the feature itself seems useless, it is a wonderful simple abstraction to see how Gatsby, Auth0, and ShareDB work together as feature-rich app ecosystem. It is based on the Counter example by ShareDB.

It should be a minimal effort to transform the data structure and user interface to any collaborative idea in your mind.

Performance

It is fast. Client and deployments are done in 60 seconds due to Netlify and Now. Gatsby does fully unleash its optimization powers.

@todo create separate PERFORMANCE.md and add lighthouse screenshot, webpagetest result & webpack stats

Setup

Requirements

You are required to use Node Version 10 since this project depends on the latest features and performance improvements.

Not on Node v10 yet?

• We recommend to use: https://github.com/creationix/nvm
• The normal way works as well: https://nodejs.org/en/download/current/

Currently, the whole project is tested on OSX only. Bugfixes to get it running smoothly on Linux and Windows are very welcome.

Installation

Via gatsby-cli:

gatsby new collaborative-app https://github.com/axe312ger/gatsby-starter-collaborative-app
cd collaborative-app

The good old manual way:

git clone https://github.com/axe312ger/gatsby-starter-collaborative-app collaborative-app
cd collaborative-app
npm install

All node dependencies for server & client are installed automatically.

One more thing: You need to have MongoDB installed for data storage. See the server README.md for instructions how to do that.

Developing

After installation, you might start the client & server at once via:

npm run dev

This will:

• Run gatsby develop in the client directory
• Start MongoDB
• Start the actual backend Server

Structure

The root directory acts as a wrapper for the client and server projects and primarily provides scripts to improve the developing and maintenance experience.

It is up to you to keep these bundled or you may just separate them. Both approaches have pros and cons.

You might first want to look into the ./client directory which is the actual Gatsby App.

The server directory provides a simple API server with Auth0 authentification and ShareDB with MongoDB.

@todo create dig deeper section into most important code files. Consider extra file for this.

Set up your own app

@todo provide guidance on how to set up your own app based on this starter.

Cleanup

You might not agree with how some things are done in this repo. No problem, here are some tips on how to get rid of several things: CLEANUP.md

Deployment setup

@todo add DEPLOYMENT.md for this

Technology Stack

The project is heavily based on well-known open source projects and cloud hosting services. The focus was to reduce server maintenance to a minimum.

Open Source Projects

• Frontend & Server Side Rendering: React via Gatsby
• Collaborative Editing: ShareDB
• DB: MongoDB
• Design: Material Design (v1) with Material UI and JSS

Services

• Frontend Hosting: Netlify
• Backend Hosting: Docker via Now.sh
• Authentication: Auth0
• Production database: MongoDB Atlas

Code origin

After all, it is a combination of the following starters, tutorials & examples:

• Collaborative functionality: https://github.com/share/sharedb/tree/master/examples/counter
• Authentification: https://auth0.com/docs/quickstart/spa/react
• Session management: https://github.com/gatsbyjs/gatsby/tree/master/examples/simple-auth
• UI: https://github.com/mui-org/material-ui/tree/master/examples/gatsby
• Forms: https://github.com/final-form/react-final-form#material-ui-10

Mentionable dependencies

Just because they rule and deserve a mention :)

• Painless form management and UX via react-final-form
• @todo complete this list

Contributing

You are very welcome to contribute. Please have a look at our Contributing Guidelines