Welcome to the PostGraphile starter

This project can serve as a basis for your own project. We've added many features that most projects require, but you're free to remove them or replace them with whatever you need.

Please read the next few sections before continuing.

Next.js and page load delays: dev only

We use Next.js to serve the React app. This gives us server-side rendering, routing, bundle splitting, hot reloading, and much more. However, in development when you visit a page it must first be loaded from the file system and transpiled and bundled by the server, served to the client, and then executed. This means there can be a small delay when loading a web page for the first time in development. In production, this delay should be vastly smaller, and can be eliminated with pre-fetching. You can read more about this in the Next.js docs

Page hangs: development only

If the page hangs this is likely because the Next server was restarted. Please reload the page.

Emails

In development we don't send any emails to real email addresses, instead all emails are sent to ethereal.email where you can browse them. Keep an eye on the terminal; when an email is triggered the server will log a URL to view the email.

GraphiQL

You can browse the GraphQL API and even issue GraphQL queries using the built in GraphiQL interface located at /graphiql.

This page: `@app/client/src/pages/index.tsx`

If you edit this file and save, the page in the browser should automatically update.

The server: `@app/server/src/index.ts`

This entry point creates an Express.js server and installs a number of middlewares, including PostGraphile.

Initial migration

We use graphile-migrate in this project to manage database migrations; this allows you to change the database very rapidly by just editing the current migration file: migrations/current.sql. This file should be written in an idempotent manner so that it can be ran repeatedly without causing issues.

We've committed the first migration for you (which builds the user system), but should you wish to customize this user system the easiest way is to run yarn db uncommit which will undo this initial migration and move its content back to current.sql for you to modify. Please see the graphile-migrate documentation.

isAdmin

The isAdmin flag doesn't do anything in this starter, but you can use it in your own applications should you need it.

What now?

To get started, click “Sign in” at the top right, then choose “Create One” to create a new account.

When you're happy, you can add database changes to current.sql and see them reflected in the GraphiQL interface a /graphiql.

Further notes

You can read this later. The important things were above; below is additional information worth a read when you're done experimenting.

Making it yours

This project isn't intended to be git clone'd; instead you should start a new git repository with the code from the latest release:

Download and extract a zip of the latest release from GitHub
In that folder run:
- git init
- git add .
- git commit -m "PostGraphile starter base"
Change the project name in package.json
Change the project settings in @app/config/src/index.ts
Replace the README.md file
Commit as you usually would

We also advise addressing the TODO items in the codebase, particularly the one in @app/db/scripts/wipe-if-demo

Production readiness

Remember that disabling GraphiQL does not prevent people from issuing arbitrary GraphQL queries against your API. Before you ship, be sure to read the Production Considerations in the PostGraphile docs. You may consider going Pro as one option for protecting your PostGraphile API; another is to use “stored operations” (a.k.a. “persisted queries”).

Realtime

We've configured PostGraphile with @graphile/pg-pubsub to enable realtime events from the DB; and Apollo is configured to consume them. For example, if you register with email/password you may notice the red dot at the top right indicating that you need to verify your email. If you verify your email in another tab (or even another browser) you should notice that this dot disappears. Realtime ✨🌈

Server-side rendering (SSR)

If you disable JS and reload the page you should see the content is still displayed (this “server-side rendering” is important to ensuring that your users have the best low-latency experience of your website, and that the majority of search engines can index its content).

Duplicate emails

To prevent people blocking legitimate users from registering, we only prevent the same email address being used multiple times when it has been verified by someone. It's up to your application to turn features off/etc when the user does not have any verified email addresses (should you desire this).

Email in production

We've configured the project to use Amazon SES to send emails in production (you will need to create the relevant resources and provide the relevant secrets to use this); however it can easily be reconfigured to use your email transport service of choice.

Validation

We use AntD's forms, so validation is provided via these. We've shown how to connect server-side errors into the form validation, for example try registering a new account using the email address of an account that has already been verified.

One-time clone: no such thing as breaking changes

It's expected that you'll do a one-time clone of this project to base your project off, and that you will not keep your project up to date with this one. As such, we can make any changes we like to this project without breaking your project.

PostGraphile relies on your support

A message from Benjie

I really hope that this project wows you 😍 and saves you huge amounts of time. I've certainly poured a lot of time into it!

Without support from the community Jem and I could not keep building and advancing these open source projects under the hugely flexible MIT license. Please join these amazing people in sponsoring PostGraphile and related projects.

Every contribution helps us to spend more time on open source.

Sponsor Graphile Today

Thank you! 🙏