JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 25
  • Score
    100M100P100Q60190F
  • License MIT

Universal embed resolver - extract embed HTML from any URL (YouTube, X/Twitter, TikTok, Facebook, Instagram, and more)

Package Exports

  • framer-framer

Readme

framer-framer

Universal embed resolver for Node.js — extract embed HTML from any URL using oEmbed APIs.

Supports YouTube, X/Twitter, TikTok, Facebook, Instagram out of the box, with OGP metadata fallback for any other URL. Zero runtime dependencies.

Install

npm install framer-framer

Requires Node.js 18+.

Usage

import { embed } from "framer-framer";

const result = await embed("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
console.log(result.html);     // <iframe width="200" height="113" src="..." ...>
console.log(result.type);     // "video"
console.log(result.title);    // "Rick Astley - Never Gonna Give You Up ..."
console.log(result.provider); // "youtube"

Platform-specific functions

import { youtube, twitter, tiktok, facebook, instagram } from "framer-framer";

await youtube("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
await twitter("https://x.com/user/status/123456789");
await tiktok("https://www.tiktok.com/@user/video/123456789");

// Facebook / Instagram require a Meta access token
await facebook("https://www.facebook.com/video/123", {
  meta: { accessToken: "APP_ID|CLIENT_TOKEN" },
});
await instagram("https://www.instagram.com/p/ABC123/", {
  meta: { accessToken: "APP_ID|CLIENT_TOKEN" },
});

Options

await embed(url, {
  maxWidth: 640,              // Max embed width
  maxHeight: 480,             // Max embed height
  fallback: true,             // OGP fallback for unknown URLs (default: true)
  meta: {                     // Required for Facebook/Instagram
    accessToken: "APP_ID|CLIENT_TOKEN",
  },
});

OGP fallback

URLs that don't match any built-in provider are resolved via OGP meta tags automatically. Disable with fallback: false.

const result = await embed("https://example.com/article", { fallback: true });
// Returns link card HTML built from og:title, og:description, og:image

Custom providers

import { registerProvider, OEmbedProvider } from "framer-framer";

class VimeoProvider extends OEmbedProvider {
  name = "vimeo";
  protected patterns = [/vimeo\.com\/\d+/];
  protected endpoint = "https://vimeo.com/api/oembed.json";
}

registerProvider(new VimeoProvider());

EmbedResult

Field Type Description
type string "rich" "video" "photo" "link"
html string Embed HTML
provider string Provider name
url string Original URL
title string? Content title
author_name string? Author name
author_url string? Author URL
thumbnail_url string? Thumbnail image URL
thumbnail_width number? Thumbnail width
thumbnail_height number? Thumbnail height
width number? Embed width
height number? Embed height
raw object? Raw oEmbed response

License

MIT