Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status NPM version Coverage Status

Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.

Key feature:

  • Supports both block & inline snippets (by default extracts data from oembed, opengraph and meta tags).
  • Light placeholders for video players to load page without delays. Iframes are loaded only after user clicks "play" button.
  • Cacheing.
  • Easy to customize and extend.
  • Dev server to test your changes.

Live Demo


npm install embedza --save

run dev server (with debug messages):

DEBUG=embedza:* npm start


Render player for youtube video:

const Embedza = require('embedza');
const embedza = new Embedza();

embedza.render('', 'block')
  .then(result => {
    if (result) console.log(result.html, result.type);


new Embedza(options)

Creates new Embedza instance with specified options:

  • enabledProviders - array of enabled providers or true for all providers, default true.
  • cache - object with .get(key) -> Promise and .set(key, value) -> Promise methods. Default stub does nothing.
  • request (optional) - any options for external requests, as described in got docs. For example, you can customize user agent header.

.render(url, type) -> Promise

Try to create HTML snippet of requested type by URL.

  • url (String|Object) - content url or result of .info().
  • type ([String]|String) - format name or list of suitable formats by priority ('block', 'inline')


  • result.html - html code
  • result.type - matched format type

If url can not be rendered - returns null. On remote errors fails with error info.

.info(url) -> Promise

Similar to .render(), but returns object with full url description.

  • url (String) - resource URL.


  • result.domain - domain plugin id ('', '', ...)
  • result.src - source url
  • result.meta - title, description, site
  • result.snippets - snippets data: type, tags, href, media, html

If url info does not exists - returns null. On remote errors fails with error info.


Iterates through domains rules to modify those.


Get domain rule by name.


Rerister new service. If String passed - enable domain with default rules. If Object passed - create custom configuration:

  • id (String) - provider ID (
  • match ([RegExp]|RegExp) - patterns to match
  • fetchers ([String|Function|Object]) - optional, array of fetchers dependency
  • mixins ([String|Function]) - optional, array of mixins dependency
  • mixinsAfter ([String|Function]) - optional, array of mixins after dependency
  • config (Object) - additional config: autoplay parameter name, API key


Add add data fetcher. Options:

  • id (String) - fetcher name.
  • priority (Number) - optional, run priority, default - 0.
  • fn (Function) - fetcher handler, async function (env).


Add mixin (data handler). Options:

  • id (String) - mixin name.
  • fn (Function) - mixin handler, async function (env).


Add post-processor "after" handler. The same as .addMixin, but handlers are axecuted after all mixins. Options:

  • id (String) - post-processor name.
  • fn (Function) - post-processor handler, async function (env).

Advanced customization


By default it's a wrapper for request. You can override it. For example to force use cache only.


Manage available templates:

const _       = require('lodash');
const Embedza = require('embedza');
const embedza = new Embedza();

// Customize templates
embedza.templates['default_inline'] = _.template('...template code...', { variable: 'self' });
embedza.templates['youtube.com_player'] = _.template('...template code...', { variable: 'self' });

// Customize template aliases
embedza.aliases.block = [ 'player', 'photo' ];

Similar projects

Embedza is inspired by projects above, but designed to satisfy our requirements. For example, it supports inline output format.




Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.







No packages published