Docs Menu

Create Template Configurations with Expansions

On this page

  • Define a Template
  • Define Environment Values
  • Define an Expansion Replacement
  • Create a New Templated App
  • Development Workflow

Realm supports a replacement operator (%()) that dynamically resolves JSON expansions like %%environment in your configuration files. When you create a new app with configuration files that include expansions (either with Realm CLI or through GitHub), Realm automatically resolves the expansions and uses the resolved configuration files to create the app.

Important

Configuration files that use the replacement operator are templates. Realm does not resolve the expansions after it creates the app. Instead, it uses a copy of the configuration files that reflect the resolved values at the time the app was created.

1

You can use expansions to template any environment. For each environment that you use, define values that you reference in your configuration files.

Example

The following environments configure different MongoDB Atlas cluster names:

environments/development.json
{
"values": {
"clusterName": "atlas-development"
}
}
environments/production.json
{
"values": {
"clusterName": "atlas-production"
}
}
2

You can reference any environment value from a configuration file with the %() replacement operator and the %%environment expansion. Define expansions for each configuration file you want to template.

Example

The following template configuration file for the mongodb-atlas data source uses expansions to dynamically resolve clusterName based on the environment:

data_sources/mongodb-atlas/config.json
{
"name": "mongodb-atlas",
"type": "mongodb-atlas",
"config": {
"clusterName": "%(%%environment.values.clusterName)",
"readPreference": "primaryPreferred",
"wireProtocolEnabled": true
}
}
3

Once you have defined your templated configuration files, you can use them to create a new app for a given environment. If you do not specify an environment, %%environment expansions resolve to values in environments/no-environment.json.

Example

Realm uses the template configuration to generate new, resolved configuration files on import:

realm-cli push --environment="development"
data_sources/mongodb-atlas/config.json
{
"name": "mongodb-atlas",
"type": "mongodb-atlas",
"config": {
"clusterName": "atlas-development",
"readPreference": "primaryPreferred",
"wireProtocolEnabled": true
}
}

You can use configuration expansions for any Realm app, but the most useful case is for teams that develop a production application with source code files stored in an external version control system like GitHub. You can create independent apps to develop features or test changes and use expansions to customize the apps based on their environment.

  1. Create a new app from the common template with the environment set to development. If you're using Git, create a new branch on GitHub and check out a local copy.
  2. Make changes and test them locally against the development app. Any changes you make to the app won't affect the production app, though they may still read and write production data sources and services unless you configure alternatives.
  3. Commit changes and merge them back to production. You can set up a CI/CD pipeline, which may itself create an app in the test environment, to validate and merge your changes into the production branch.
  4. Once your changes are merged, you can safely delete the development app and clean up any other associated services.
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.