supabase-express-api

• tsx
• pkgroll
• eslint
• prettier
• typescript
• vitest
• zod
• drizzle
  • drizzle with supabase
• drizzle-zod
• drizzle-kit
• postgres
• supabase
  • supabase-js
• helmet
• cookie-parser
• @sentry/node

A node/express backend API template for getting started with a new project that includes authentication, permissions, and a database configured to use Supabase or a local/cloud Postgres database.

This comes pre-defined with a workspaces model that allows accounts (users) to create workspaces and invite other profiles (users presence within a workspace) to access the workspace (membership). see the Permissions section for more information on how permissions are defined.

The contents of a workspace is not defined in this template and can be customized to suit the needs of the project.

ESM Node

https://www.typescriptlang.org/docs/handbook/esm-node.html

This project has been setup to use ESM Node. This allows us to use ES6 imports in Node.

This uses tsx as a dev server and pkgroll to bundle and build the project.

Requirements

This project requires node.js to be installed. This project uses volta to manage node versions.

To install volta run the following command in the terminal.

curl https://get.volta.sh | bash

You will need a Postgres database to run this project. You can use Docker to run a Postgres database or use a service like Supabase. The auth provider can be replaced with any other Auth providers eg Firebase, Auth0, Keycloak you just need to implement the authentication middleware to verify the token and decode the claims and modify the auth handlers to use your provider.

See the Database section for more information on how to configure the database connection.

Authentication is handled by Supabase and requires a Supabase account. You can sign up for a free account at supabase.com.

Install PNPM

If using volta we can install corepack globally and let volta manage the binary, corepack will let us use the correct version of pnpm based on the packageManager field in the package.json file.

npm install --global corepack@latest

corepack enable pnpm

see the installation docs for pnpm and the corepack docs for more information on how to install pnpm and corepack.

ENV

Create a .env file in the root of the project and copy the contents of .env.example into it.

cp .env.example .env

see the section on Deployment with DigitalOcean for more information on how to configure the environment variables for deployment in different environments (eg. development and production).

Install dependencies

pnpm i

Setup the database

The first time setting up the database you will need to run the migrate command to create the database tables and apply the migrations.

pnpm run migrate

Testing

This project uses vitest for unit testing.

Run the unit tests with npm run test

It's also recommended to install the vitest extension for vscode.

Supabase CLI

You can install the supabase cli for local development.

• https://supabase.com/docs/guides/cli/getting-started
• https://supabase.com/docs/guides/cli/local-development

Database

You can view the database with pnpx drizzle-kit studio or pnpm run studio.

You can spin up a local copy of the database and application with docker-compose but this is not required when using the Supabase db.

When using the supabase cli we can run a local copy of the db with supabase start.

Developing locally with supabase

This will provide you with a connection string, you can update the local environment variables in the .env file with the details from the connection string.

postgresql://postgres:postgres@localhost:54322/postgres

Visit the Supabase dashboard: http://localhost:54323 and manage your database locally. Note: It appears that the database name needs to be postgres to be able to work with the Supabase dashboard.

Local Postgres with Docker

You can spin up a local database and application with docker-compose but this is not required when using the Supabase db or cli.

docker compose up -d

Alternatively you can create a local network and connect the containers to the network.

docker network create mynetwork

docker run --network mynetwork --name mypostgres -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=example -e POSTGRES_DB=postgres postgres:15

Then when running the application in docker you can connect to the database with the container name.

POSTGRES_HOST=mypostgres

Then run the application in docker and connect to the same network.

docker run --network mynetwork --name node-express -d -p 4000:4000 node-express

Note: If you are using a local database and running the application within docker on the host machine you will need to set POSTGRES_HOST=host.docker.internal in the .env file. Read the docs for more info

Migrations

When running the migrations for the first time on a new database run:

pnpm run migrate

When the schema/model is changed make sure to create a new migration and run it against the db.

1. Create a new migration

pnpm run migrate:create

2. Run the migrations

# first run the migrations
pnpm run migrate:up

# then run
pnpm migrate:push

Seeds

You can run the seeds to populate the database with initial data.

Before seeding the db make sure to run the migrations. If you want to populate the seeds with specific user email, password or id's related to the users created in Supabase. You can update the seeds in ./src/seeds/ with the required data.

You will need to add these users to supabase auth and confirm the email addresses.

pnpm run seed

Be sure to update the seeds as new migrations are added.

Build with docker

# build the app
npm run build

# build with docker
docker build . --tag node-express

# or to build with a specific platform
docker build . --tag node-express --platform linux/amd64

# or build a specific stage eg dev
docker build . --target dev --tag node-express

# start the docker container
docker run -d -p 4000:4000 node-express

# view it running on localhost
curl localhost:4000

Import aliases

Aliases can be configured in the import map, defined in package.json#imports.

see: https://github.com/privatenumber/pkgroll#aliases

Authentication

This project uses JWT bearer token for authentication. The claims, id and sub must be set on the token and the token can be verified and decoded using the configured auth provider.

Permissions

How permissions work.

A resource will have a permission level for each route method based on users role within the workspace. Workspace permissions can be defined in ./src/helpers/permissions.ts.

Workspace level permissions: Admin: Highest level of access to all resources within the workspace. User: Regular user with limited permissions.

Resource level permissions: Owner: Has access to their own resources

Account level permissions: SuperAdmin: Has access to all super only resources.

Workspace route permission levels

Ensure every request that requires workspace permissions includes a workspace context.

This can be done by passing the x-workspace-id header when making a request.

This will allow the user to access the workspace resources if they are a member of the workspace with a sufficient role.

A role/claim is defined when the account is added to the workspace as a member.

1. User - Can access all resources with user permissions.
2. Admin - Can access all resources within the workspace.

Supabase Auth

see the documentation for more information on how to use Supabase Auth with this project.

Deployment with DigitalOcean

A docker image can be built and deployed to a container registry. We can configure DigitalOcean to deploy the image once the registry updates using their App Platform

The following secrets will need to be added to Github Actions for a successful deployment to DigitalOcean.

Environment variables for deployment

• DIGITALOCEAN_ACCESS_TOKEN https://docs.digitalocean.com/reference/api/create-personal-access-token/
• REGISTRY_NAME eg registry.digitalocean.com/my-container-registry
• IMAGE_NAME the name of the image we are pushing to the repository eg express-api it will be tagged with the latest version and a github sha.

App level environment variables

For information on confguring the app level environment variables see How to use environment variables in DigitalOcean App Platform

• NODE_ENV: production
• APP_URL: https://api.example.com
• POSTGRES_HOST: <region>.pooler.supabase.com
• POSTGRES_USER: postgres.<supabase-id>
• POSTGRES_PASSWORD: example
• POSTGRES_DB: postgres
• SUPABASE_URL: https://<supabase-id>.supabase.co
• SUPABASE_PK: abcdefghijklm