Ember CLI Server Variables

4.0.0 · active · verified Tue Apr 21

ember-cli-server-variables is an Ember CLI addon designed to inject server-driven variables into the `<head>` section of an Ember application's `index.html` file during the build process. These variables are typically used for dynamic configurations like API tokens, user location, or other environment-specific data provided by the application server. The current stable version is 4.0.0, which requires Ember.js v4.12+ and Node.js v18+. The addon's release cadence is generally tied to Ember CLI and Ember.js major version updates, ensuring compatibility with the latest ecosystem standards. It differentiates itself by providing a convenient service for accessing these variables within the Ember application, abstracting away the parsing of meta tags. Its core functionality involves configuring a list of expected variables in `config/environment.js`, optionally providing development defaults, and then consuming them via an injected service. Since version 2.0.0, it automatically parses JSON string values in the meta tags, simplifying data retrieval for structured configuration.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'appToken')
```
cause The `serverVariables` service was not properly injected into the component or controller attempting to access it, or the variable name was not defined in `config/environment.js`.

fix Verify the service is correctly injected using `Ember.inject.service('serverVariables')` (classic) or `@service serverVariables;` (modern Octane). Also, confirm the variable's dasherized name is in `ENV.serverVariables.vars` in `config/environment.js`.
```
SyntaxError: Unexpected token 'o' in JSON at position X (or similar JSON parsing error from `JSON.parse`)
```
cause You are likely attempting to manually `JSON.parse()` a server variable's value after upgrading to version 2.0.0 or later, where the addon automatically handles JSON string parsing.

fix Remove any explicit `JSON.parse()` calls for variables fetched from `serverVariablesService` that are expected to be JSON. The service will return JavaScript objects directly for such variables.
```
Meta tag for 'my-app-api-key' not found in index.html, or variable not available in service.
```
cause This error or similar behavior (variable always being an empty string) indicates either the `{{content-for 'server-variables'}}` placeholder is missing, the variable was not included in the `vars` array in `config/environment.js`, or the server serving `index.html` did not populate the meta tag's `content` attribute.

fix 1. Check `app/index.html` for `{{content-for 'server-variables'}}`. 2. Ensure the variable is listed in `ENV.serverVariables.vars`. 3. Confirm your server-side logic correctly inserts the meta tag with the expected name and content into the generated `index.html`.

Warnings

breaking Version 4.0.0 introduces breaking changes primarily due to updating Ember to v5.12.0. Your Ember application must meet the updated peer dependency requirements.
Fix: Upgrade your Ember.js and Ember CLI versions to match the addon's peer dependencies: Ember.js v4.12+, Ember CLI v4.12+, and Node.js v18+. Refer to official Ember upgrade guides for detailed migration steps.
breaking Version 2.0.0 introduced automatic JSON parsing for server variables. If you were previously manually calling `JSON.parse()` on variables retrieved from the service that were expected to be JSON strings, this will now lead to errors or double-parsing.
Fix: Remove any manual `JSON.parse()` calls for variables that are expected to be JSON strings. The `serverVariables` service automatically handles the parsing for you.
gotcha The `{{content-for 'server-variables'}}` tag is crucial and must be present within the `<head>` section of your `app/index.html` file. If this placeholder is missing, the addon cannot inject the necessary `<meta>` tags, and server variables will not be available to your application.
Fix: Ensure `{{content-for 'server-variables'}}` is manually added to your `app/index.html` file, typically after `{{content-for 'head'}}` or `{{content-for 'head-footer'}}`.
gotcha The `vars` array within the `serverVariables` block in your `config/environment.js` is a required configuration. Without it, the addon will not know which server variables to look for or expose through its service.
Fix: Ensure `ENV.serverVariables.vars` is an array containing the dasherized names of all server variables your application expects to consume, e.g., `vars: ['api-key', 'feature-flags']`.

Install

npm install ember-cli-server-variables npm
yarn add ember-cli-server-variables yarn
pnpm add ember-cli-server-variables pnpm

Imports

serverVariablesService
wrong:
```
import { serverVariablesService } from 'ember-cli-server-variables';
```
correct:
```
import Ember from 'ember';

// In a classic Ember component or controller
export default Ember.Component.extend({
  serverVariablesService: Ember.inject.service('serverVariables'),
  // ...
});
```
This addon provides a service that is consumed via Ember's dependency injection system, not a direct named import from the package itself. For modern Ember (Octane+), you would typically use the `@service` decorator: `import { service } from '@ember/service'; class MyComponent extends Component { @service serverVariablesService; // ... }`

Configuration

wrong:

import config from 'ember-cli-server-variables/environment';

correct:

// config/environment.js
module.exports = function(environment) {
  let ENV = { /* ... */ };
  ENV.serverVariables = {
    tagPrefix: 'your-app',
    vars: ['my-variable', 'json-data']
  };
  return ENV;
};

Configuration for this addon is done directly in your Ember app's `config/environment.js` file, within the `ENV.serverVariables` object. There is no direct import for addon configuration. The addon hooks into the Ember CLI build process.

Quickstart

This quickstart demonstrates how to configure server variables and their development defaults in `config/environment.js`, and then access them within an Ember Octane component using the `@service` decorator, including both string and automatically parsed JSON variables.

/* config/environment.js */
module.exports = function(environment) {
  let ENV = {
    modulePrefix: 'my-ember-app', // Used as default tagPrefix if not explicitly set
    // ... other ENV settings for your Ember application
    serverVariables: {
      tagPrefix: 'my-app',
      vars: ['app-token', 'user-location', 'json-config'] // Define variables expected from server
    }
  };

  if (environment === 'development') {
    // Provide default values for development environment
    ENV.serverVariables.defaults = {
      'app-token': 'dev-secret-token-123',
      'user-location': 'Localhost, Earth',
      'json-config': '{"featureA":true,"level":5}' // JSON strings are auto-parsed
    };
  }

  return ENV;
};

/* app/components/variable-display.js (example modern Ember Octane component) */
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { tracked } from '@glimmer/tracking';

export default class VariableDisplayComponent extends Component {
  @service serverVariables; // Inject the service

  @tracked token = '';
  @tracked location = '';
  @tracked config = {};

  constructor() {
    super(...arguments);
    // Access variables; properties are camelCased from dasherized config
    this.token = this.serverVariables.appToken; 
    this.location = this.serverVariables.userLocation;
    this.config = this.serverVariables.jsonConfig; // Automatically parsed JSON
    
    console.log('Server Variables Loaded:', {
      appToken: this.token,
      userLocation: this.location,
      jsonConfig: this.config
    });
    // Render these variables in your component's template (e.g., this.token in {{this.token}})
  }
}

view raw JSON →