Skip to main content
We’ve made optional functionality available to MongoDB customers that handles the backend integration required by PowerSync. This makes PowerSync easier to implement for developers migrating from MongoDB Atlas Device Sync who prefer not having to maintain their own backend code and infrastructure (PowerSync’s typical architecture is to use your own backend to process mutations uploaded from clients, and to generate JWTs for authentication if needed). Specifically, you can use the CloudCode feature of JourneyApps Platform, a sibling product of PowerSync. CloudCode is a serverless cloud functions engine based on Node.js and AWS Lambda. It’s provided as a fully-managed service running on the same cloud infrastructure as the rest of PowerSync Cloud. PowerSync and JourneyApps Platform share the same login system, so you don’t need to create a separate account to use CloudCode. For further background, see this post on our blog.
We are currently making JourneyApps Platform CloudCode available for free to all our customers who use PowerSync with MongoDB. It does require a bit of “white glove” onboarding from our team. Contact us if you want to use this functionality.

​
Using CloudCode for MongoDB Backend Functionality

There is a MongoDB template available in CloudCode that provides the backend functionality needed for a PowerSync MongoDB implementation. Here is how to use it:

​
Create a New JourneyApps Platform Project

To create a new JourneyApps Platform project in order to use CloudCode:
1
Navigate to the JourneyApps Admin Portal. You should see a list of your projects if you’ve created any.
2
Select Create Project at the top right of the screen.
3
Select JourneyApps Platform Project and click Next.
4
Enter a project name and click Next.
5
There are options available for managing version control for the project. For simplicity we recommend selecting Basic (Revisions) and JourneyApps as the Git provider.
6
Select TypeScript as your template language, and MongoDB CRUD & Auth Backend as your template. Then click Create App.

​
Overview of the CloudCode Tasks Created From the Template

To view the CloudCode tasks that were created in the new project using this template, select CloudCode at the top of the IDE:
Here you will find four CloudCode tasks:
Here’s the purpose of each task:
TaskUsed ForDescription
generate_keysAuthentication IntegrationThis is a task that can be used to generate a private/public key pair which the jwks and token tasks (see below) require. This task does not expose an HTTP endpoint and should only be used for development and getting started.
jwksAuthentication IntegrationThis task exposes an HTTP endpoint which has a GET function which returns the public JWKS details.
tokenAuthentication IntegrationThis task exposes an HTTP endpoint which has a GET function. The HTTP endpoint can be called by your fetchCredentials() function when implementing the PowerSync Client SDK, to generate a JWT that the Client SDK can use to authenticate against the PowerSync Service.
uploadClient MutationsThis task exposes an HTTP endpoint which has a POST function which is used to process uploaded mutations from a PowerSync client and persist it to the source MongoDB database. The HTTP endpoint can be called by your uploadData() function when implementing the PowerSync Client SDK.
If you will not be using Custom Authentication, you do not need the authentication-related tasks. Some authentication providers (e.g. Auth0, Clerk, Stytch, Keycloak, Azure AD, Google Identity, WorkOS, etc.) already generate JWTs for users which PowerSync can work with directly. If you are not using one of those authentication providers, you will need to implement Custom Authentication

​
Setup: Deployment Configuration

Before using the tasks, we need to configure a “deployment”.
  1. At the top of the IDE, select Deployments.
  2. Create a new deployment by using the + button at the top right, or use the default Testing deployment. You can configure different deployments for different environments (e.g. staging, production)
  3. Now select the Deployment settings button for the deployment.
  4. In the Deployment settings - General tab, capture a Domain value in the text field. This domain name determines where the HTTP endpoints exposed by these CloudCode tasks can be accessed. The application will validate the domain name to make sure it’s available.
  5. Select Save.
  6. Deploy the deployment: you can do so by selecting the Deploy app button, which can be found on the far right for each of the deployments you have configured. After the deployment is completed, it will take a few minutes for the domain to be available.
  7. Your new domain will be available at <domain_name>.poweredbyjourney.com. Open the browser and navigate to the new domain. You should be presented with Cannot GET /, because there is no index route.

​
Setup: Authentication Integration (Optional)

If you will not be using Custom Authentication, you can skip this part. See the explanatory note about authentication above.

​
1. Generate Key Pair

First, you need to generate a public/private key pair. Do the following to generate the key pair:
  1. Open the generate_keys CloudCode task.
  2. Select the Test CloudCode Task button at the top right. This will print the public and private key in the task logs window.
  1. Copy and paste the POWERSYNC_PUBLIC_KEY and POWERSYNC_PRIVATE_KEY to a file — we’ll need this in the next step.
This step is only meant for testing and development because the keys are printed in the log files. For production, generate a key pair locally and move onto step 2 and 3.

​
2. Configure Environment Variables

The following variables need to be set on the deployment for authentication integration purposes:
  • POWERSYNC_PUBLIC_KEY - This is the POWERSYNC_PUBLIC_KEY from the values generated in step 1.
  • POWERSYNC_PRIVATE_KEY - This is the POWERSYNC_PRIVATE_KEY from the values generated in step 1.
  • POWERSYNC_URL - This is your PowerSync instance URL that can be found in the PowerSync Dashboard.
See the How to Set Environment Variables section below for instructions.

​
3. Test

Open your browser and navigate to <domain_name>.poweredbyjourney.com/jwks (using the domain name you picked in Setup: Deployment Configuration) If the setup was successful, the jwks task will render the keys in JSON format. Make sure the format of your JWKS keys matches the format in this example JWKS endpoint.

​
Setup: Handling Client Mutations

The following variables need to be set on the deployment for the purpose of handling uploaded client mutations:
  • POWERSYNC_URL - This is your PowerSync instance URL that can be found in the PowerSync Dashboard.
  • MONGO_URI - This is the URI of your MongoDB source database e.g. mongodb+srv://<username>:<password>@<database_domain>/<database>
See the next section for instructions.

​
How to Set Environment Variables

To set environment variables, do the following:
  1. At the top of the IDE, select Deployments.
  2. Click on Deployment settings for the relevant deployment.
  3. Select the Environment Variables tab.
  1. Capture the variable name in the Name text field.
  2. Capture the variable value in the Value text field.
  3. (Suggested) Check the Masked checkbox to obfuscate the variable value for security purposes.
  4. Repeat until all the variables are added.
To finalize the setup, do the following:
  1. Select the Save button. This is important, otherwise the variables will not save.
  2. Deploy the deployment: you can do so by selecting the Deploy app button.

​
Usage: Authentication Integration (Optional)

Make sure you’ve configured a deployment and set up environment variables as described in the Setup steps above before using the HTTP API endpoints exposed by the CloudCode tasks

​
Token

You would call the token HTTP API endpoint when you implement the fetchCredentials() function in your client application. Send an HTTP GET request to <domain_name>.poweredbyjourney.com/token?user_id=<user_id> to fetch a JWT for a user. You must provide a user_id in the query string of the request, as this is included in the JWT that is generated. The response of the request will be structured like this: 
{"token":"..."}

​
JWKS

The jwks HTTP API endpoint is used by PowerSync to validate the token returned from the <domain_name>.poweredbyjourney.com/token endpoint. This URL must be set in the configuration of your PowerSync instance. Send an HTTP GET request to <domain_name>.poweredbyjourney.com/jwks. An example of the response format can be found using this link.

​
Usage: Handling Client Mutations

​
Upload

You would call the upload HTTP API endpoint when you implement the uploadData() function in your client application. Send an HTTP POST request to <domain_name>.poweredbyjourney.com/upload The body of the request payload should look like this: 
{
  "batch": [{
    "op": "PUT",
    "table": "lists",
    "id": "61d19021-0565-4686-acc4-3ea4f8c48839",
    "data": {
      "created_at": "2024-10-31 10:33:24",
      "name": "Name",
      "owner_id": "8ea4310a-b7c0-4dd7-ae54-51d6e1596b83"
    }
  }]
}
  • batch should be an array of mutations from the PowerSync Client SDK.
  • op refers to the type of each mutation recorded by the PowerSync Client SDK (PUT, PATCH or DELETE). Refer to Writing Data and Writing Client Changes for details.
  • table refers to the table in SQLite where the mutation originates from, and should match the name of a collection in MongoDB.
The API will respond with HTTP status 200 if the write was successful.

​
Customization: Handling Client Mutations

You can make changes to the way the upload task writes data to the source MongoDB database. Here is how:
  1. Go to CloudCode at the top of the IDE in your JourneyApps Platform project
  2. Select and expand the upload task in the panel on the left.
  3. The index.ts contains the entry point function that accepts the HTTP request and has a MongoDBStorage class which interacts with the MongoDB database to perform inserts, updates and deletes. To adjust how mutations are performed, take a look at the updateBatch function.

​
Production Considerations

Before going into production with this solution, you will need to set up authentication on the HTTP endpoints exposed by the CloudCode tasks. If you need more data validations and/or authorization than what is provided by the template, that will need to be customized too. Consider introducing schema validation of the data being written to the source MongoDB database. You should use a purpose-built library for this, and use MongoDB Schema Validation to enforce the types in the database. Please contact us for assistance on any of the above.