PostGraphile Boilerplate - Vue/Nuxt.js & Apollo & Docker

This repository will help you get started with PostGraphile quickly. It's currently a work in progress, but despite this it should be a good jumping-off point.

Goals:

Database:

• Basic setup script to setup/reset database (yarn setup)
• Basic migrations system with migrate/rollback commands (yarn db:migrate:dev / yarn db:rollback:dev)
• Migration templating to support different role names
• Dump database after every migration to ensure everyone's running the same

Server:

• PostGraphile server, with Express
• Development: GraphiQL (enhanced)
• Development: watch DB for changes, no need to restart server
• Development: maintain up-to-date GraphQL schema file (./data/schema.graphql)
• Session-based authentication (cookies)
• Database migrations framework (preferably flexible)
• User accounts (registration, login)
• OAuth support (login with GitHub, Twitter, Facebook, ... via Passport.js)
• Double-submit token to avoid CSRF
• Background worker
• Server-side rendering (SSR)
• Test suite

Client:

• Vue/Nuxt.js app
• Development mode has hot loading
• vue-apollo GraphQL client
• Send double-submit token (if present) with GraphQL requests (window.CSRF_TOKEN)
• Routing via Nuxt.js Router
• Register/login with social providers
• Register with username/password
• Login with username/password
• vue ui working
• Storybook for Vue component previews
• Test suite
• Automatic bundle splitting

General:

• JavaScript linting
• GraphQL linting
• Prettier for code formatting
• Ignore relevant files in GitHub PRs (gitattributes linguist-generated=true)
• Production-optimised bundle

Deployment:

• Procfile for Heroku
• Dockerfile or similar

Layout

The project is split into the following folders:

• /db - everything related to the database: migrations, unit tests, etc
• /data - generated data, such as the GraphQL and database schema dumps
• /server/pages - everything related to the web browser / client: the Vue components, routes, etc see
• /server - everything related to running the server: the middlewares, PostGraphile configuration, SSR, integration tests, etc
• /server/tasks - background tasks run by Graphile Worker

We currently use a root-level package.json between all of them. In future we might take a monorepo approach using yarn workspaces, but for now we figured simplicity wins.

Tools

We use the following tools to make our life easier

• PostGraphile (obviously) to turn our database into a GraphQL API, and to output the GraphQL schema for other tools
• Apollo Client to consume this GraphQL API and manage caching
• Vue/Nuxt.js for rendering
• Webpack to bundle everything up
• ESLint for powerful linting and autocorrection
• Prettier for consistent code formatting
• Express.js to implement our server
• db-migrate for performing migrations
• graphile-worker for running background tasks

Getting Started

Prerequisites:

• docker
• docker-compose.

# Create and configure database
yarn setup

# Start everything
yarn start

Then load http://localhost:8080

{TODO}

Environmental Variables

This package is configured through environmental variables. yarn setup creates a .env file for you which you can then customise.

Conventions

See db/CONVENTIONS.md.

{TODO}

Deploying

{TODO}

Database layout

• public - this is where extensions are installed to, it also contains the migrations table. We will typically not add anything to this schema ourselves.
• app_public - contains everything to be exposed over GraphQL
• app_hidden - same permissions as app_public, but will not be exposed over GraphQL
• app_private - database-owner-only storage, for storing things users should never have direct access to, like bcrypt password hashes.

Why the /data folder?

ESLint needs an up to date schema dump to correctly validate GraphQL queries.

When developing, you want to ensure that your database is identical to your colleagues - differences in /data/schema.sql indicate that your databases differ.

When performing Code Review, it's important to see the changes to both the database and the GraphQL schemas to ensure no breaking changes are introduced.