Graphile Starter

Graphile Starter is an open-source, MIT-licensed full-stack boilerplate that gives you a pre-built user account and organization system for React, Node.js, GraphQL, and PostgreSQL applications, managing everything from database migrations to background jobs.

What is Graphile Starter?

Graphile Starter is an opinionated quick-start project for full-stack application development in React, Node.js, GraphQL and PostgreSQL. It includes a complete user registration system, organizations (teams or companies), session management, a job queue, tests at both granular and end-to-end levels, and a significant amount of pre-configured tooling. The project is maintained by the Graphile community and released under the MIT license, and it ships with deployment instructions for Heroku and Docker.

Key Features

Graphile Starter ships with a wide range of pre-configured functionality covering the full stack, from authentication to background jobs to deployment. The main features are:

• Batteries included — Full user system with email verification, GitHub OAuth social login, organizations, session management, and an account deletion feature.
• Full-stack TypeScript — The entire stack is written in TypeScript, with GraphQL types and React hooks auto-generated via GraphQL Code Generator.
• PostGraphile backend — An Express.js server uses PostGraphile in library mode to expose a GraphQL API directly from the PostgreSQL schema.
• Next.js frontend — Server-side rendering and routing via Next.js, with the Ant Design (AntD) framework for UI components.
• Graphile Worker job queue — Background tasks such as sending emails are processed by Graphile Worker, which runs alongside the server.
• Idempotent database migrations — Graphile Migrate watches migrations/current.sql and automatically applies changes during development, with the ability to commit migrations for production.
• Pre-configured testing — Jest runs unit and integration tests in watch mode, and Cypress is set up for end-to-end testing.
• Developer experience — Hot reloading, VSCode plugin recommendations, ESLint, Prettier, and debugger profiles are included out of the box.
• Production-ready deployment — A production Dockerfile can build a server or worker image, and a heroku-setup script automates Heroku deployment with Amazon RDS and Redis.

Who is it for?

Graphile Starter suits anyone who wants to start a full-stack web application without building account and organization boilerplate from scratch. The intended audiences include:

• Hackathon participants — Go from idea to a working full-stack app in one day by using the pre-built auth, organizations, and email system.
• Web agencies and freelancers — Use as a foundation for client projects to avoid rebuilding authentication, background jobs, and testing setup for every new site.
• Solo developers and side-hustlers — Skip boilerplate and focus on product logic, with easy deployment to Heroku or Docker.
• Developers learning advanced tooling — The README explicitly warns it is NOT for beginners, but it serves as a reference implementation of PostGraphile, Graphile Worker, Graphile Migrate, and TypeScript in a real project.

Use cases

Graphile Starter's pre-built account system and job queue make it a fit for a variety of products. Common uses include:

• SaaS product with accounts — Launch a multi-tenant app with user sign-up, login, password reset, email verification, and organizations out of the box.
• Client projects — Use as an agency starting point for any web app that needs authentication, a job queue, and server-side rendering.
• Open-source experiments — Build a side project on a free MIT-licensed base, with the option to sponsor the project to support ongoing development.

How does Graphile Starter work?

Graphile Starter is started with yarn start, which concurrently launches several development tools. The main command watches the database schema, compiles server TypeScript, runs the Node server, runs graphile-worker, generates React hooks, and runs tests in watch mode. The application is accessible at http://localhost:5678.

Pricing

Graphile Starter is free and open source under the MIT license. The project relies on donations and sponsorship to continue development, and a list of sponsors is included in the README.

FAQ

Is Graphile Starter for beginners?

No. The README explicitly states it is NOT for beginners and recommends being comfortable with Node.js, Express, PostgreSQL, GraphQL, PostGraphile, Graphile Worker, Graphile Migrate, TypeScript, React, Apollo Client, GraphQL Code Generator, ESLint, Prettier, Jest, and Cypress before using it as a base.

What are the prerequisites for local development?

Local mode requires Node.js v16+ and PostgreSQL v10+ with pg_dump available. Alternatively, Docker mode uses docker and docker-compose, and you should allocate Docker at least 4GB of RAM.

How do I start the project?

Run yarn to install dependencies, then yarn setup to create a .env file. For development, run yarn start (or yarn docker start in Docker mode) and open http://localhost:5678.

Can I deploy Graphile Starter to Heroku?

Yes. The repository includes a heroku-setup script that creates the Heroku app, adds a Redis extension, creates database roles and passwords, sets config variables, and pushes your initial build. It also documents configuring Amazon SES for email and GitHub OAuth for social login.

Does Graphile Starter include a job queue?

Yes. It uses Graphile Worker to execute background tasks such as sending emails, and this worker process is started automatically as part of yarn start.