Graphile Starter

Take it for a spin!

We're running the starter at:

https://graphile-starter.herokuapp.com

Feel free to register an account and have a poke around as you see fit.

NOTE: emails are sent from Graphile Starter, so please only enter email addresses you control.

NOTE: every time we merge to master, we ship a new version of Graphile Starter to Heroku and entirely wipe the database, so your data may not persist. If you wish to delete your data before this time you can do so via the delete account feature baked into the starter.

NOT FOR BEGINNERS

We do not advise that you build your own projects on top of this project until you're comfortable with the various tools it uses (Node.js, Express, PostgreSQL, GraphQL, PostGraphile, Graphile Worker, Graphile Migrate, TypeScript, React, Apollo Client for React, GraphQL Code Generator, ESLint, Prettier, Jest, Cypress, etc).

This is an advanced project with deeply integrated tooling across the full stack. The project is called "Starter" because it helps you to start new projects with all these technologies, tools and techniques already in place. If you're not already familiar with these things then you'll probably find the project overwhelming, it is not intended to be your first experience of any of these tools.

If you're just getting started with PostGraphile, before you dive into this project make sure you check out the PostGraphile required knowledge and especially the schema design tutorial. This repository takes a slightly different approach to schema design than the aforementioned tutorial, but it's still an incredibly valuable resource.

Purpose

Graphile Starter is an opinionated quick-start project for full-stack application development in React, Node.js, GraphQL and PostgreSQL. It includes the foundations of a modern web application, with a full user registration system, organizations (e.g. teams/companies/etc), session management, optimized job queue, a significant amount of pre-configured tooling, tests (both end-to-end and more granular) and much more.

It is suitable for building projects both large and small, with a focus on productivity. You might use it:

to go from conception to launch of a web app during a hack day
as the foundation for client projects at your web agency
to build your side-hustle without spending lots of time on boilerplate
to build a SaaS project to help fund your open source work 😉

However you use it, the project can be deployed to many platforms, and can be scaled to larger audiences both horizontally and vertically with very few changes.

Please note that this software is not "complete," free of software defects, or free of security issues — it is not a "finished" solution, but rather the seed of a solution which you should review, customize, fix, and develop further.

It is intended that you use a "point in time" version of this software ─ it is not intended that you can merge updates to this software into your own derivative in an automated fashion.

Crowd-funded open-source software

PLEASE DONATE.

Take this software and use it as the starting point to build your project. Go make some money, and give something back to support us building more tools and kits for the Node, GraphQL and PostgreSQL ecosystems. We have made this project available under the simple and liberal MIT license to give you to a huge amount of freedom in how you use it, but this isn't possible without the help of our wonderful sponsors.

We need more people to join our sponsors so we can continue to bring about awesome projects like this. We'd love to spend more time on open source, building tools that will save you and others even more time and money ─ please sponsor our open source efforts:

Click here to find out more about sponsors and sponsorship.

And please give some love to our featured sponsors 🤩:

<table><tr> <td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td> <td align="center"><a href="https://gosteelhead.com/"><img src="https://graphile.org/images/sponsors/steelhead.svg" width="90" height="90" alt="Steelhead" /><br />Steelhead</a> *</td> </tr></table>

<em>* Sponsors the entire Graphile suite</em>

Graphile Starter

Features

Graphile Starter is a full-stack GraphQL and React project, with server-side rendering (SSR) and routing thanks to Next.js. The backend is a beautiful pairing of Node.js and PostgreSQL running on Express.js, enabled by PostGraphile in library mode. The frontend uses the AntD design framework to accelerate development. The entire stack is written in TypeScript, with auto-generated GraphQL types and operations thanks to graphql-code-generator.

There are four tenets to Graphile Starter:

Speedy development
Batteries included
Type safety
Best practices

Graphile Starter is easy to start and everything is pre-configured as much as possible.

Speedy development: hot reloading, easy debugging, Graphile's idempotent migration system, job queue and server middleware ready to use; not to mention deep integration with VSCode should you use that editor: plugin recommendations, pre-configured settings, ESLint and Prettier integration and debugging profiles

Batteries included: full user system and OAuth, AntD design framework, Jest and Cypress end-to-end testing, security, email templating and transport, pre-configured linting and code formatting, deployment instructions, and more

Type safety: pre-configured type checking, strongly typed throughout with TypeScript

Best practices: React, GraphQL, PostGraphile, Node, Jest and Cypress best practices

See TECHNICAL_DECISIONS.md for a more detailed list of features included and the technical decisions behind them.

Variants

Since this is a highly opinionated starter; community members may have slightly different opinions and may choose to maintain forks of this project that apply their own opinions. A few of these are listed below; if you maintain a fork of this project please make a note at the top of your own README, and add it to this list:

Vue 3 + Vite SSR variant - replaces Next.js with Vue and Vite SSR
Nuxt.js variant - replaces Next.js for Vue users
Create React App variant - replaces Next.js for apps without Server Side Rendering
Remix variant - replaces Next.js with Remix
Sveltekit variant - replaces Next.js with Sveltekit

VARIANTS ARE NOT OFFICIALLY SUPPORTED and may become out of date or unmaintained over time. If you have issues with variants, please submit issues or PRs to the projects in question, not to this project.

Prerequisites

You can either work with this project locally (directly on your machine) or use a pre-configured Docker environment. We'll differentiate this in the README with a table like this one:

| Local mode | OR | Docker mode | | ------------------------------- | :-: | ---------------------------------------- | | command for local development | or | command for docker-compose development |

Be careful not to mix and match Docker-mode vs local-mode for development. You should make a choice and stick to it. (Developing locally but deploying with production.Docker is absolutely fine.)

IMPORTANT: If you choose the Docker mode, be sure to read [docker/READM

Starter

Install / Use

README