` element. ```js { metaInfo: { title: 'Foo Bar' } } ``` ```html <title>Foo Bar

vue-meta

Manage page meta info in Vue 2.0 components. SSR + Streaming supported. Inspired by react-helmet.

```html ``` # Table of Contents - [Description](#description) - [Disclaimer](#disclaimer) - [Installation](#installation) - [Yarn](#yarn) - [NPM](#npm) - [CDN](#cdn) - [Usage](#usage) - [Step 1: Preparing the plugin](#step-1-preparing-the-plugin) - [Step 2: Server Rendering (Optional)](#step-2-server-rendering-optional) - [Step 2.1: Exposing `$meta` to `bundleRenderer`](#step-21-exposing-meta-to-bundlerenderer) - [Step 2.2: Populating the document meta info with `inject()`](#step-22-populating-the-document-meta-info-with-inject) - [Simple Rendering with `renderToString()`](#simple-rendering-with-rendertostring) - [Streaming Rendering with `renderToStream()`](#streaming-rendering-with-rendertostream) - [Step 3: Start defining `metaInfo`](#step-3-start-defining-metainfo) - [Recognized `metaInfo` Properties](#recognized-metainfo-properties) - [`title` (String)](#title-string) - [`titleTemplate` (String)](#titletemplate-string) - [`htmlAttrs` (Object)](#htmlattrs-object) - [`bodyAttrs` (Object)](#bodyattrs-object) - [`base` (Object)](#base-object) - [`meta` ([Object])](#meta-object) - [`link` ([Object])](#link-object) - [`style` ([Object])](#style-object) - [`script` ([Object])](#script-object) - [`noscript` ([Object])](#noscript-object) - [`changed` (Function)](#changed-function) - [How `metaInfo` is Resolved](#how-metainfo-is-resolved) - [Lists of Tags](#lists-of-tags) - [Performance](#performance) - [How to prevent the update on the initial page render](#how-to-prevent-the-update-on-the-initial-page-render) - [FAQ](#faq) - [How do I use component data in `metaInfo`?](#how-do-i-use-component-data-in-metainfo) - [How do I use component props in `metaInfo`?](#how-do-i-use-component-props-in-metainfo) # Description `vue-meta` is a [Vue 2.0](https://vuejs.org) plugin that allows you to manage your app's meta information, much like [`react-helmet`](https://github.com/nfl/react-helmet) does for React. However, instead of setting your data as props passed to a proprietary component, you simply export it as part of your component's data using the `metaInfo` property. These properties, when set on a deeply nested component, will cleverly overwrite their parent components' `metaInfo`, thereby enabling custom info for each top-level view as well as coupling meta info directly to deeply nested subcomponents for more maintainable code. # Disclaimer **Please note** that this project is still in very early alpha development and is *not* considered to be production ready. **You have been warned.** There is no sanitization yet, no tests, and you might even find some features are still missing. # Installation ### Yarn ```sh $ yarn add vue-meta ``` ### NPM ```sh $ npm install vue-meta --save ``` ### CDN Use the links below - if you want a previous version, check the instructions at https://unpkg.com. **Uncompressed:** ```html ``` **Minified:** ```html ``` # Usage ## Step 1: Preparing the plugin > This step is optional if you don't need SSR and `Vue` is available as a global variable. `vue-meta` will install itself in this case. In order to use this plugin, you first need to pass it to `Vue.use` - if you're not rendering on the server-side, your JS entry file will suffice. If you are rendering on the server, then place it in a file that runs both on the server and on the client before your root instance is mounted. If you're using [`vue-router`](https://github.com/vuejs/vue-router), then your main `router.js` file is a good place: **router.js:** ```js import Vue from 'vue' import Router from 'vue-router' import Meta from 'vue-meta' Vue.use(Router) Vue.use(Meta) export default new Router({ ... }) ``` If you don't care about server-side rendering, you can skip straight to [step 3](#step-3-start-defining-metainfo). Otherwise, continue. :smile: ## Step 2: Server Rendering (Optional) If you have an isomorphic/universal webapp, you'll likely want to render your metadata on the server side as well. Here's how. ### Step 2.1: Exposing `$meta` to `bundleRenderer` You'll need to expose the results of the `$meta` method that `vue-meta` adds to the Vue instance to the bundle render context before you can begin injecting your meta information. You'll need to do this in your server entry file: **server-entry.js:** ```js import app from './app' const router = app.$router const meta = app.$meta() // here export default (context) => { router.push(context.url) context.meta = meta // and here return app } ``` ### Step 2.2: Populating the document meta info with `inject()` All that's left for you to do now before you can begin using `metaInfo` options in your components is to make sure they work on the server by `inject`-ing them so you can call `text()` on each item to render out the necessary info. You have two methods at your disposal: #### Simple Rendering with `renderToString()` Considerably the easiest method to wrap your head around is if your Vue server markup is rendered out as a string: **server.js:** ```js app.get('*', (req, res) => { const context = { url: req.url } renderer.renderToString(context, (error, html) => { if (error) return res.send(error.stack) const { title, htmlAttrs, bodyAttrs, link, style, script, noscript, meta } = context.meta.inject() return res.send(` ${meta.text()} ${title.text()} ${link.text()} ${style.text()} ${script.text()} ${noscript.text()} ${html} `) }) }) ``` #### Streaming Rendering with `renderToStream()` A little more complex, but well worth it, is to instead stream your response. `vue-meta` supports streaming with no effort (on it's part :stuck_out_tongue_winking_eye:) thanks to Vue's clever `bundleRenderer` context injection: **server.js** ```js app.get('*', (req, res) => { const context = { url: req.url } const renderStream = renderer.renderToStream(context) renderStream.once('data', () => { const { title, htmlAttrs, bodyAttrs, link, style, script, noscript, meta } = context.meta.inject() res.write(` ${meta.text()} ${title.text()} ${link.text()} ${style.text()} ${script.text()} ${noscript.text()} `) }) renderStream.on('data', (chunk) => { res.write(chunk) }) renderStream.on('end', () => { res.end(` `) }) renderStream.on('error', (error) => res.status(500).end(`

${error.stack}

`)) }) ``` ## Step 3: Start defining `metaInfo` In any of your components, define a `metaInfo` property: **App.vue:** ```html ``` **Home.vue** ```html ``` **About.vue** ```html ``` ### Recognized `metaInfo` Properties #### `title` (String) Maps to the inner-text value of the `` element. ```js { metaInfo: { title: 'Foo Bar' } } ``` ```html <title>Foo Bar ``` #### `titleTemplate` (String) The value of `title` will be injected into the `%s` placeholder in `titleTemplate` before being rendered. The original title will be available on `metaInfo.titleChunk`. ```js { metaInfo: { title: 'Foo Bar', titleTemplate: '%s - Baz' } } ``` ```html Foo Bar - Baz ``` #### `htmlAttrs` (Object) Each **key:value** maps to the equivalent **attribute:value** of the `` element. ```js { metaInfo: { htmlAttrs: { foo: 'bar', amp: undefined } } } ``` ```html ``` #### `bodyAttrs` (Object) Each **key:value** maps to the equivalent **attribute:value** of the `` element. ```js { metaInfo: { bodyAttrs: { bar: 'baz' } } } ``` ```html Foo Bar ``` #### `base` (Object) Maps to a newly-created `` element, where object properties map to attributes. ```js { metaInfo: { base: { target: '_blank', href: '/' } } } ``` ```html ``` #### `meta` ([Object]) Each item in the array maps to a newly-created `` element, where object properties map to attributes. ```js { metaInfo: { meta: [ { charset: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' } ] } } ``` ```html ``` #### `link` ([Object]) Each item in the array maps to a newly-created `` element, where object properties map to attributes. ```js { metaInfo: { link: [ { rel: 'stylesheet', src: '/css/index.css' }, { rel: 'favicon', src: 'favicon.ico' } ] } } ``` ```html ``` #### `style` ([Object]) Each item in the array maps to a newly-created ` ``` #### `script` ([Object]) Each item in the array maps to a newly-created ` ``` #### `noscript` ([Object]) Each item in the array maps to a newly-created `

This website requires JavaScript.

``` #### `changed` (Function) Will be called when the client `metaInfo` updates/changes. Receives the following parameters: - `newInfo` (Object) - The new state of the `metaInfo` object. - `addedTags` ([HTMLElement]) - a list of elements that were added. - `removedTags` ([HTMLElement]) - a list of elements that were removed. `this` context is the component instance `changed` is defined on. ```js { metaInfo: { changed (newInfo, addedTags, removedTags) { console.log('Meta info was updated!') } } } ``` ### How `metaInfo` is Resolved You can define a `metaInfo` property on any component in the tree. Child components that have `metaInfo` will recursively merge their `metaInfo` into the parent context, overwriting any duplicate properties. To better illustrate, consider this component heirarchy: ```html ``` If both `` _and_ `` define a `title` property inside `metaInfo`, then the `title` that gets rendered will resolve to the `title` defined inside ``. #### Lists of Tags When specifying an array in `metaInfo`, like in the below examples, the default behaviour is to simply concatenate the lists. **Input:** ```js // parent component { metaInfo: { meta: [ { charset: 'utf-8' }, { name: 'description', content: 'foo' } ] } } // child component { metaInfo: { meta: [ { name: 'description', content: 'bar' } ] } } ``` **Output:** ```html ``` This is not what we want, since the meta `description` needs to be unique for every page. If you want to change this behaviour such that `description` is instead replaced, then give it a `vmid`: **Input:** ```js // parent component { metaInfo: { meta: [ { charset: 'utf-8' }, { vmid: 'description', name: 'description', content: 'foo' } ] } } // child component { metaInfo: { meta: [ { vmid: 'description', name: 'description', content: 'bar' } ] } } ``` **Output:** ```html ``` While solutions like `react-helmet` manage the occurrence order and merge behaviour for you automatically, it involves a lot more code and is therefore prone to failure in some edge-cases, whereas this method is _almost_ bulletproof because of its versatility; _at the expense of one tradeoff:_ these `vmid` properties will be rendered out in the final markup (`vue-meta` uses these client-side to prevent duplicating or overriding markup). If you are serving your content GZIP'ped, then the slight increase in HTTP payload size is negligible. # Performance On the client, `vue-meta` batches DOM updates using [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame). It needs to do this because it registers a Vue mixin that subscribes to the [`beforeMount`](https://vuejs.org/api/#beforeMount) lifecycle hook on all components in order to be notified that renders have occurred and data is ready. If `vue-meta` did not batch updates, the DOM meta info would be re-calculated and re-updated for every component on the page in quick-succession. Thanks to batch updating, the update will only occurr once - even if the correct meta info has already been compiled by the server. If you don't want this behaviour, see below. ### How to prevent the update on the initial page render Add the `data-vue-meta-server-rendered` attribute to the `` tag on the server-side: ```html ... ``` `vue-meta` will check for this attribute whenever it attempts to update the DOM - if it exists, `vue-meta` will just remove it and perform no updates. If it does not exist, `vue-meta` will perform updates as usual. > **Note:** While this may seem verbose, it _is_ intentional. Having `vue-meta` handle this for you automatically would limit interoperability with other server-side programming languages. If you use PHP to power your server, for example, you might also have meta info handled on the server already and want to prevent this extraneous update. # FAQ Here are some answers to some frequently asked questions. ## How do I use component data in `metaInfo`? Specify a function instead of an object. It will need to return the same type as its definition. **BlogPost.vue:** ```html ``` ## How do I use component props in `metaInfo`? The same way you use data - specify a function instead of an object. It will need to return the same type as its definition. **BlogPostWrapper.vue** ```html ``` **BlogPost.vue** ```html ```

Manage page meta info in Vue 2.0 components. SSR + Streaming supported. Inspired by react-helmet.

Home Page

About Page

{{ title }}

{{ title }}