Providers

A Provider is an object that tells the library how to detect and embed a specific media service (e.g., YouTube, Vimeo, Spotify, or your own custom platform). Each Provider has a common interface with methods to:

1. Check if a URL can be parsed (e.g., canParseUrl(url)).
2. Extract relevant identifiers from that URL (e.g., getIdFromUrl(url)).
3. Generate an “embed-ready” URL from those identifiers (e.g., getEmbedUrlFromId(id, ...args)).

What Is a Provider?#

Each provider implements the EmbedProvider interface:

See the API reference for the full type definition.

Built-in Providers#

@social-embed/lib ships with built-in providers for:

• YouTube
• Vimeo
• Spotify
• Loom
• Wistia
• EdPuzzle
• DailyMotion

For each, the library has a default implementation that can detect (regex) and parse typical URL forms. This is how convertUrlToEmbedUrl(url) automatically recognizes, for instance, a YouTube or Vimeo link.

Adding a Custom Provider#

If you want to support a media service that @social-embed/lib doesn’t cover out-of-the-box, you can implement a custom provider object.

1. Write Your Provider#

Here’s a minimal example for a hypothetical “MyCustom” service:

import type { EmbedProvider } from "@social-embed/lib";

export const MyCustomProvider: EmbedProvider = {
  name: "MyCustom",

  // Return true if URL matches your domain/format
  canParseUrl(url: string) {
    // e.g. "https://mycustom.example.com/video/<id>"
    return /mycustom\.example\.com\/video\//.test(url);
  },

  // Extract the ID from the URL. In this example, we assume the last path segment is the ID.
  getIdFromUrl(url: string) {
    const segments = url.split("/");
    return segments.pop() ?? "";
  },

  // Construct the final embed URL from the ID plus any optional arguments
  getEmbedUrlFromId(id: string, ...args: unknown[]) {
    // For example, "https://mycustom.example.com/embed/<id>"
    return `https://mycustom.example.com/embed/${id}`;
  },
};

2. Register It in the Default Registry#

If you want your custom provider to work with convertUrlToEmbedUrl(url) or other “automatic” detection calls, you can register it in the default registry:

import { defaultRegistry } from "@social-embed/lib";
import { MyCustomProvider } from "./MyCustomProvider";

// Register your new provider
defaultRegistry.register(MyCustomProvider);

// Now `convertUrlToEmbedUrl()` should handle MyCustom links
import { convertUrlToEmbedUrl } from "@social-embed/lib";

console.log(
  convertUrlToEmbedUrl("https://mycustom.example.com/video/xyz123"),
);
// "https://mycustom.example.com/embed/xyz123"

3. Or Use a Separate Registry (Optional)#

If you don’t want to modify the default registry, you can create your own EmbedProviderRegistry instance:

import { EmbedProviderRegistry } from "@social-embed/lib";
import { MyCustomProvider } from "./MyCustomProvider";

const myRegistry = new EmbedProviderRegistry();
myRegistry.register(MyCustomProvider);

// Then do something like:
const provider = myRegistry.findProviderByUrl("https://mycustom.example.com/video/xyz123");
if (provider) {
  const id = provider.getIdFromUrl("https://mycustom.example.com/video/xyz123");
  // ...
}

This approach can be useful if you’re building a specialized environment or want to keep built-in providers separate from your custom ones.

Typical Workflow#

1. canParseUrl(url) => boolean
   • The library checks each registered provider in turn until one returns true.
2. getIdFromUrl(url) => string|string[]
   • Once we know which provider matches, we call this to extract the crucial bits (e.g. ["id", "type"]).
3. getEmbedUrlFromId(id, ...args) => string
   • Finally, we build the actual iframe link from the ID and any optional arguments.

Further Reading#

• Examples: Real code samples for built-in providers
• Registry Tests: Where you can see how we test provider detection and embed URL generation
• @social-embed/wc: A web component (<o-embed>) that uses these providers under the hood

In short: A Provider is basically a “plugin” that knows how to detect a certain service’s URLs and generate embed-friendly links. You can rely on built-in providers for mainstream services or create your own for any custom media flow!