/toiletmap

API/UI server for the Great British Public Toilet Map

Primary LanguageTypeScriptMIT LicenseMIT

toiletmap.org.uk

Public Convenience Ltd's Great British Public Toilet Map

Powered by Vercel

What is the Toilet Map?

Everyone will, at some point in the day, need to use the toilet. Some people will need facilities more than others, and some will need to find toilets sooner rather than later.

The Great British Public Toilet Map aims to be a complete, up-to-date, sustainable source of toilet locations. It's the UK's largest database of publicly-accessible toilets, with over 14,000 facilities.

The project is completely open source and is supported by a fantastic set of Sponsors who help us make the service as good as it can possibly be.

This documentation is oriented towards developers, if you'd like to learn more about our data and how to access it please refer to Toilet Map Explorer.

Getting Started

The following is a "quick start" guide aimed at getting you started with a development environment to start hacking on the map. If you'd like to configure Auth0 for local authentication or run our end to end tests locally please take a look at our more in-depth setup documentation.

Prerequisites

  • fnm (or a node version matching the one specified in .nvmrc)
  • pnpm
  • Docker to spin up a local postgres database to develop against.
  • Vercel CLI (optional)

Installation

Clone or download and unpack the project and change into its directory and then use your favourite node version manager to switch to the version defined in our .nvmrc. We use fnm as a demonstration, although alternative are available such as asdf and nvm:

fnm use

Now we install the dependencies using the pnpm package manager:

pnpm install

Run, Toiletmap, Run

First we need a set of local environment variables:

cp .env.local.example .env.local

Next you'll need to set up a local instance of Postgres based on our mocked loo data. This is so that you can load something on your local instance of the Toilet Map. We use the Supabase development container to spin up a local version of the same platform that we currently use in stage and production.

Note It's also possible to connect directly to our staging database, although you'll need to ask for those credentials should you need them.

pnpm supabase:start

When you run this command, 5000 mock toilets and UK area boundaries will be loaded from seed.sql. The loos in use here are pre-generated using faker.js in generateMocks.ts.

Because the faker generation is set with a static seed, the values remain the same between generations. This is important, because we depend upon the values remaining the same in our cypress tests so we have a deterministic set of data to rely upon across our test runs.

Once you have a local Postgres instance running you'll then be able to spin up a local development server using the following command:

pnpm dev

If all is well, upon navigation to http://localhost:3000 you will be presented with your very own instance of the Toilet Map that is connected to the local Postgres database that you have just set up.

If you'd like to make contributions to the project this is a good time to read our contributing guidelines and our code of conduct.

Architecture

The Toilet Map UI is built with Next.js. The API is written in GraphQL with GraphQL Yoga Server and data is stored in a Postgres database hosted by Supabase. We connect to the database through the Prisma ORM. Authentication is handled by Auth0 and the site is deployed to vercel

Sponsors

Our brilliant sponsors help us to bring a stable and high quality service to our users.

Vercel

Powered by Vercel

Vercel sponsor the hosting and deployment of the Next.js based Toilet Map, allowing us to scale confidently and iterate quickly using their versatile platform.

Sentry

Logging is kindly sponsored by Sentry

Our client and server side logging in production is kindly sponsored by Sentry.

Cypress

Cypress dashboard enhances our development workflow when working with our Cypress test suite

Cypress Dashboard speeds up and enhances our testing workflow, helping us to deliver changes faster and with fewer bugs.


Looking to help? Let us know