Public Convenience Ltd's 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 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.
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.
- 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)
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
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.
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
Our brilliant sponsors help us to bring a stable and high quality service to our users.
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.
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