This addon lets you populate <head> tag from your Ember code without any direct hacky DOM manipulation. It also provides ember-cli-fastboot compatibility for generating head tags in server-rendered apps.
The hope is that, in the future, Ember will provide a mechanism for populating <head> tag from your app. Until then, this addon provides that functionality.
- Ember.js v3.16 or above
- Ember CLI v3.16 or above
- Node.js v12 or above
Install by running
ember install ember-cli-headAdd <HeadLayout /> to the top of your application template.
// app/templates/application.gjs
import { HeadLayout } from 'ember-cli-head';
<template>
<HeadLayout>
<meta property="og:title" content="My App">
</HeadLayout>
{{outlet}}
</template>The contents of HeadLayout's defaukt block will be inserted into the <head> element of the page.
// app/routes/application.ts
import Route from '@ember/routing/route';
import { service } from '@ember/service';
import HeadDataService from 'app/services/head-data';
export default class ApplicationRoute extends Route {
@service declare headData: HeadDataService;
afterModel() {
this.headData.title = 'Demo App';
}
}// app/services/head-data.ts
import Route from '@ember/routing/route';
import Service from '@ember/service';
import { tracked } from '@glimmer/tracking';}
export default class HeadDataService extends Service {
@tracked declare title: string;
}// app/services/head-data.gts
import { service } from '@ember/service';
import Component from '@glimmer/component';
export default class Head extends Component {
@service('head-data') declare model: HeadDataService;
<template>
<meta property="og:title" content={{this.model.title}} />
</template>
}// app/templates/application.gts
import { HeadLayout } from 'ember-cli-head';
import Head from 'app/components/head';
<template>
<HeadLayout><Head /></HeadLayout>
{{outlet}}
</template>This will result in a document along the lines of:
<html data-ember-extension="1">
<head>
...
<meta name="ember-cli-head-start" content>
<meta property="og:title" content="Demo App">
<meta name="ember-cli-head-end" content>
</head>
<body class="ember-application">
...
</body>
</html>The primary need for this addon is to support various bots and web crawlers. To that end, the head content is only truly needed in a server-rendered environment like FastBoot.
By default, the addon will keep the head content in sync with any route transitions and data changes that occur when your Ember app runs in the browser. This can be useful for development and debugging.
If you don't wish the head content to be "live" when the app runs in browser, you can restrict this addon to run only in FastBoot:
// config/environment.js
module.exports = function(environment) {
let ENV = {
'ember-cli-head': {
suppressBrowserRender: true
}
};
return ENV;
};If you use suppressBrowserRender, the content of <head> will be the static FastBoot-rendered content throughout your app's lifecycle.
As of 3.x you need ember-auto-import installed and configured to use this addon with Ember CLI applications. See the ember-auto-import documentation for details.
The addon doesn't provide any boilerplate code anymore. You will need to create your own head component and inject the headData service.
- Move your head.hbs template to components.
- In your new head component, add
@service headDatainjection. - If you don't have head-data service, you will have to create it.
As previously mentioned, you need to add the <HeadLayout /> component once and only once in an application-wide template. This template is usually app/templates/application.hbs but may be different in your case.
Prior to 0.4, the component was appended to the document inside an instance initializer. This prevented the need for the <HeadLayout /> component as it was automatically injected and used inside that initializer. This approach needed to change so that we could render the component with the rest of the application rendering.
In short, if you are upgrading to 0.4.x, you simply add the <HeadLayout /> component to your application-wide template.
See the Contributing guide for details.
This project is licensed under the MIT License.