Client-Side Setup

We recommend splitting up your client-side implementation into four phases:

1. Generate a development token

2. Run the Diagnostics app with the development token

3. Use the client SDK with the development token

4. Implement authentication

1. Generate Development Token

The recommended approach is to initially use a short-lived development token and then wire up production auth at a later stage.

To generate a development token, the process is:

1. Generate a temporary private/public key-pair for JWT signing and verification

2. Set the public key in your PowerSync Service configuration file (config.yaml or config.json)

3. Save the private/public key into an .env file

4. Generate a key, loading the .env file and inputting a user UUID. See example script:

import * as jose from 'jose';

// get this from env / config?
const powerSyncPrivateKey = {
  kty: 'oct',
  k: '...',
  kid: 'powersync-dev',
  alg: 'HS256'
};
const powerSyncKey = (await jose.importJWK(powerSyncPrivateKey)) as jose.KeyLike;

const token = await new jose.SignJWT({})
  .setProtectedHeader({
    alg: powerSyncPrivateKey.alg!,
    kid: powerSyncPrivateKey.kid
  })
  .setSubject('b29a2678-91c3-406a-9109-2cb99bcc6a01') // set user id, maybe as cli arg
  .setIssuedAt()
  // .setIssuer()
  .setAudience('powersync-dev')
  .setExpirationTime('12h')
  .sign(powerSyncKey);

console.log(token);

2. Run the Diagnostics app using a development token

With the Diagnostics web app you can quickly inspect a user's local database. By using this you can confirm that the PowerSync Service configuration and sync rules behave as expected without needing to set up authentication or app UI.

Install and run the app

Start by cloning the PowerSync JS monorepo:

git clone https://github.com/powersync-ja/powersync-js.git

In the root of the repository, run:

pnpm install
pnpm build:packages

Then in the tools/diagnostics-app directory run:

pnpm dev

Sign into app

Enter the generated token into the app's sign in screen.

Enter your PowerSync Service endpoint (see the port number specified in your config file e.g. http://localhost:8080).

Checkpoint:

Inspect your global bucket and synced table (from the PowerSync Service Setup section) in the diagnostics app — these should match the sync rules you defined previously.

3. Use the Client SDK with a development token

Install the PowerSync client SDK in your app. Refer to the client-side installation instructions here: Client-Side Setup

Hardcode the development token you generated above in the fetchCredentials method, which you'll implement as part of Integrate with your Backend

4. Implement authentication

Read about how authentication works in PowerSync here: Authentication Setup

If you are using Supabase or Firebase authentication, PowerSync can verify JWTs for users directly:

Supabase Auth

Under client_auth in your config file, enable supabase authentication:

# config.yaml

client_auth:
  # Enable this if using Supabase Auth
  supabase: true

For more details, see Supabase Auth.

Firebase Auth

Under client_auth in your config file, add your Firebase JWKS URI and audience.

• JWKS URI: https://www.googleapis.com/service_accounts/v1/jwk/[e-mail]

• JWT Audience: Your Firebase project ID

# config.yaml

client_auth:
  # JWKS URIs can be specified here.
  jwks_uri: 
'https://www.googleapis.com/service_accounts/v1/jwk/[e-mail]'

  audience: ['<your Firebase project ID>']

For more details, see Firebase Auth.

Custom auth

Refer to: Custom

PowerSync supports both RS256 and HS256. Insert your auth details into your configuration file:

# config.yaml

client_auth:
  # JWKS URIs can be specified here.
  jwks_uri: http://demo-backend:6060/api/auth/keys

  # Optional static collection of public keys for JWT verification
  # jwks:
  #   keys:
  #     - kty: 'RSA'
  #       n: '${PS_JWK_N}'
  #       e: '${PS_JWK_E}'
  #       alg: 'RS256'
  #       kid: '${PS_JWK_KID}'

  audience: ['powersync-dev', 'powersync']