ember-runtime-config

ember-runtime-config

Configure an Ember application with server-side environment variables

Normally, if you want to configure your Ember application on a per-environment basis, you can access the environment at build-time in config/environment.js and use that in your application.

But what happens if you want to build your application once, but still configure the application based on the environment?

This addon allows you to do just that!

Compatibility

• Ember.js v3.28 or above
• Embroider or ember-auto-import v2

Installation

ember install ember-runtime-config

Then, edit the configuration in config/ember-runtime-config.js to define the variables you want access to in your application.

To access the variables from the client, you can import the environment like so:

import env from 'ember-runtime-config';

Additionally, yu may use template helper runtime-config to access the variables in the template like so:

{{runtime-config "SOME_KEY"}}

Usage

In development, the environment will be exposed to your Ember application automatically by hooking into the development server.

In a production environment, it's assumed that you're using an Express-like Node server for your assets. You can import the middleware and add it to your own server.

const app = require('express')();
const emberRuntimeConfig = require('ember-runtime-config/middleware');

app.use(emberRuntimeConfig('/path/to/ember/app/root'));

app.listen(3000, () => {
  console.log('Server running');
});

To have access to runtime variables in fastboot mode add runtime-config properties within the sandbox:

// config/fastboot.js or config/fastboot-testing.js
const { dirname } = require('path');

module.exports = function () {
  return {
    buildSandboxGlobals(defaultGlobals) {
      let fastbootOnlyConfig = {
        SOME_KEY: 'fastbootOnly'
      };

      return Object.assign(
        {},
        defaultGlobals,
        require('ember-runtime-config/fastboot').buildSandboxGlobals(
          dirname(__dirname),
          fastbootOnlyConfig
        )
      );
    },
  };
};

More info can be found in ember-cli-fastboot.

Test helpers

setRuntimeConfig set custom config in application.

Example:

import { setRuntimeConfig } from 'ember-runtime-config/test-support';

module('Acceptance | Awesome test', function (hooks) {
  setupApplicationTest(hooks);

  test('updating an environment variable and accessing it', async function (assert) {
    setRuntimeConfig({
      GREETING: 'Welcome!'
    });

    await visit('/');

    assert.dom('h1').hasText('Welcome!');
  });
});

TypeScript

The library ships with full support for TypeScript usage. The API described above works as expected, with one additional nicety and one caveat.

Nicety: the library provides you the ability to define statically known feature flags by using a registry (as you may be familiar with from the registries for Ember's services, Ember Data models, etc.). If you define your keys in a registry like this:

// types/index.d.ts, with other types defined for your app

declare module 'ember-runtime-config/registry' {
  export default interface Registry {
    'prop-a': boolean;
    'prop-b': string;
  }
}

Then in your app code, you will get type checking: TS will require you to use one of those keys and reject unknown keys.

import Component from '@glimmer/component';
import runtimeConfig from 'ember-runtime-config';
 
export default class Example extends Component {
  get imagePrefix() {
    return runtimeConfig['prop-a']; // ✅
  }

  get whoops() {
    return runtimeConfig.propX; // ❌
  }
}

This applies to all the values. If you do not add any keys to the Registry interface, the types will fall back to simply allowing any string and returning a unknown value.

This project ships Glint types, which allow you when using TypeScript to get strict type checking in your templates.

Unless you are using strict mode templates (via first class component templates), Glint needs a Template Registry that contains entries for the element modifier provided by this addon. To add these registry entries automatically to your app, you just need to import ember-runtime-config/template-registry from somewhere in your app. When using Glint already, you will likely have a file like types/glint.d.ts where you already import glint types, so just add the import there:

import '@glint/environment-ember-loose';

import type EmberRuntimeConfigRegistry from 'ember-runtime-config/template-registry';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry extends EmberRuntimeConfigRegistry, /* other addon registries */ {
    // local entries
  }
}

Stability

This library provides type definitions and follows the current draft of the Semantic Versioning for TypeScript Types specification. The public API is all published types. It currently supports TypeScript 5.0 - 5.5.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Changelog

v2.0.1 (2024-08-22)

:memo: Documentation

• ember-runtime-config
  • #22 (docs) fix typescript support version (@SergeAstapov)

Committers: 1

• Sergey Astapov (@SergeAstapov)