PowerSync Node.js Backend: Todo List Demo

Overview

This repo contains a demo Node.js server application which has HTTP endpoints to authorize a PowerSync enabled application to sync data between a client device and a PostgreSQL, MySQL, MSSQL or MongoDB database.

The endpoints are as follows:

1. GET /api/auth/token

   • PowerSync uses this endpoint to retrieve a JWT access token which is used for authentication.
   • Provide an optional user_id url query parameter to set the subject of the JWT

2. POST /api/auth/token

   • PowerSync uses this endpoint to retrieve a JWT access token which is used for authentication.
   • Provide an optional user_id url query parameter to set the subject of the JWT
   • Provide a JSON body to the request to set custom claims in the JWT

3. GET /api/auth/keys

   • PowerSync uses this endpoint to validate the JWT returned from the endpoint above.

4. PUT /api/data

   • PowerSync uses this endpoint to sync upsert events that occurred on the client application.

5. PATCH /api/data

   • PowerSync uses this endpoint to sync update events that occurred on the client application.

6. DELETE /api/data

   • PowerSync uses this endpoint to sync delete events that occurred on the client application.

7. PUT /api/attachments/:id

   • PowerSync uses this endpoint to upload a file for use with the attachments API.

8. GET /api/attachments/:id

   • PowerSync uses this endpoint to download a previously uploaded attachment.

9. DELETE /api/attachments/:id

   • PowerSync uses this endpoint to delete a previously uploaded attachment.

Attachments are stored on the local filesystem under attachments/ for demo purposes only — there is no auth on these endpoints and the directory is ephemeral under Docker. For production, back the client's storage adapter with an object store (S3, Cloudflare R2, Supabase Storage, etc.).

Packages

node-postgres is used to interact with the Postgres database when a client performs requests to the /api/data endpoint.

mongodb is used to interact with the MongoDB database when a client performs requests to the /api/data endpoint.

mysql2 is used to interact with the MySQL database when a client performs requests to the /api/data endpoint.

node-mssql is used to connect to a MSSQL database to perform operations from the /api/data endpoint.

jose is used to sign the JWT which PowerSync uses for authorization.

Requirements

Based on configuration, this app needs a Postgres, Mongo, MSSQL or MySQL instance. Easiest is probably to use docker containers for these databases. Hosted free versions that can also be used:

1. Postgres: For a free version for testing/demo purposes, visit Supabase.
2. MSSQL: For a free version of Azure SQL for testing/demo purposes, visit Azure SQL.

Running the app

1. Clone the repository
2. Follow the steps outlined in PowerSync Custom Authentication Example → Generate a key-pair to get the keys you need for this app. This is an easy way to get started with this demo app. You can use your own public/private keys as well. Note: This backend will generate a temporary key pair for development purposes if the keys are not present in the .env file. This should not be used in production.
3. Create a new .env file in the root project directory and add the variables as defined in the .env file:

cp .env.template .env

4. Install dependancies

nvm use

pnpm install

Start App

1. Run the following to start the application

pnpm start

This will start the app on http://127.0.0.1:PORT, where PORT is what you specify in your .env file.

2. Test if the app is working by opening http://127.0.0.1:PORT/api/auth/token/ in the browser

3. You should get a JSON object as the response to that request

Connecting the app with PowerSync

This process is only designed for demo/testing purposes, and is not intended for production use. You won't be using ngrok to host your application and database.

1. Download and install ngrok
2. Run the ngrok command to create a HTTPS tunnel to your local application

ngrok http 8000

This should create the tunnel and a new HTTPS URL should be availible e.g.

ngrok by @inconshreveable                                                                                                                  (Ctrl+C to quit)

Session Status                online
Account                       Michael Barnes (Plan: Free)
Update                        update available (version 2.3.41, Ctrl-U to update)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://your_id.ngrok-free.app -> http://localhost:8000
Forwarding                    https://your_id.ngrok-free.app -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              1957    0       0.04    0.03    0.01    89.93

3. Open the PowerSync Dashboard and paste the Forwarding URL starting with HTTPS into the Credentials tab of your PowerSync instance e.g.

JWKS URI
https://your_id.ngrok-free.app/api/auth/keys/

Pay special attention to the URL, it should include the /api/auth/keys/ path as this is used by the PowerSync server to validate tokens.