Skip to content
Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.
JavaScript CSS HTML
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


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


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.



You can’t perform that action at this time.