ember-cli-embedded

Control how your Ember applications boot in non-Ember pages/apps.

Showing:

Popularity

Downloads/wk

202

GitHub Stars

10

Maintenance

Last Commit

21hrs ago

Contributors

11

Package

Dependencies

3

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

ember-cli-embedded

CI Ember Observer Score License: MIT

Makes it easier to embed your Ember application in another (non-Ember) app.

This addon gives you more control over how and when your Ember app will boot and also allows to add/override some configuration, so that the Ember app can boot with some context-dependent config.

We found it especially useful, for example, when migrating an existing app to Ember part by part.

Compatibility

  • Ember.js v3.20 or above
  • Ember CLI v3.20 or above
  • Node.js v12 or above

Usage

Installation

ember install ember-cli-embedded

Configuration

This plugin is opt-in by default, it does nothing to your app unless you configure it.

In your config/environment.js, add the following config to the ENV:

  let ENV = {
    ...
    embedded: {
      delegateStart: true,
      config: { // optional
        // Default values for the config passed at boot
      },
    },
    ...
  };

Doing so will make your application hold, until your manually start it. (read on to lear more)

For compatibility reasons, this behaviour will work as long as the value of embedded is truthy but we plan to remove it in a future version.
Please stick to the config format above.

Start your app

This addon relies on ember-export-application-global to get your application globally exposed. See its documentation for more information.

In your JS code, just execute MyApp.start(/* optionalConfig */) to resume the boot of your application. As per the example, it takes an optional configuration as its first argument.

Remember: Your app will not start unless you call the MyApp.start(/* optionalConfig */) method.

Access the config from your application

Via the Service embedded

Consider the following config/environment.js file:

  let ENV = {
    ...
    embedded: {
      config: {
        option1: 'value-1',
      },
    },
    ...
  };

And the application is started that way:

<script>
  MyApp.start({ option2: 'value-2' });
</script>

Then in your Services, Components, Controllers...

class MyService extends Service {
  @service embedded;

  @action
  logSomeConfigKey() {
    // Will log 'value-1'
    console.log(this.embedded.option1);
  }
}

Via the container itself

Sometimes it can be more convenient to access the data directly from the container.

Following the previous example:

import { getOwner } from '@ember/application';

...

// Returns the raw config
let embeddedConfig = getOwner(this).lookup('config:embedded');

// Will log 'value-2'
console.log(embeddedConfig.option2);

Override your APP configuration

The startup object will be merged into your APP configuration key, which is very useful, for instance, if you want to change the rootElement of your application and other context-sensitive values.

Consider the following config/environment.js file:

  let ENV = {
    APP: {
      rootElement: `#some-element`,
    },

    embedded: {
      config: {
        option1: 'value-1',
      },
    },
  };

And the application is started that way:

<script>
  MyApp.start({ option2: 'value-2' });
</script>

This would result in:

import APP_ENV_CONFIG from 'my-app/config/environment'

assert.deepEqual(
  APP_ENV_CONFIG,
  {
    APP: {
      option2: 'value-2',
      rootElement: `#some-element`,
    },

    embedded: {
      config: {
        option1: 'value-1',
      },
    },
  }
);

About the test environment

In your tests suite, you will probably want to let your application start automatically without this addon interfering.

To do that, make sure to disable the addon for the test environment:

// file `config/environment.js`

if (environment === 'test') {
  ENV.embedded.delegateStart = false;
}

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100