@embedly/nextjs

A simple, lightweight React component library for embedding content via Embedly's OEmbed API in Next.js applications.

Features

• ✅ Simple React component for rendering embeds
• ✅ Full TypeScript support with comprehensive types
• ✅ Server-side API utility for secure key handling
• ✅ Supports all OEmbed types (video, photo, rich, link)
• ✅ Customizable loading and error states
• ✅ Works with both App Router and Pages Router
• ✅ Zero dependencies (except React and Next.js peer deps)

Installation

npm install @embedly/nextjs

Quick Start

1. Get an Embedly API Key

Sign up at embed.ly and get your API key.

2. Add API Key to Environment Variables

Create a .env.local file in your Next.js project:

EMBEDLY_API_KEY=your_api_key_here

3. Create an API Route

The API key must be kept server-side for security. Create an API route to proxy requests to Embedly.

App Router (Next.js 13+)

Create app/api/embedly/route.ts:

import { NextRequest, NextResponse } from 'next/server';
import { fetchEmbedlyData } from '@embedly/nextjs';

export async function GET(request: NextRequest) {
  const apiKey = process.env.EMBEDLY_API_KEY;

  if (!apiKey) {
    return NextResponse.json(
      { error: 'Embedly API key not configured' },
      { status: 500 }
    );
  }

  const searchParams = request.nextUrl.searchParams;
  const url = searchParams.get('url');

  if (!url) {
    return NextResponse.json(
      { error: 'URL parameter is required' },
      { status: 400 }
    );
  }

  try {
    const embedData = await fetchEmbedlyData(apiKey, {
      url,
      maxWidth: searchParams.get('maxWidth') 
        ? parseInt(searchParams.get('maxWidth')!, 10) 
        : undefined,
      maxHeight: searchParams.get('maxHeight')
        ? parseInt(searchParams.get('maxHeight')!, 10)
        : undefined,
    });

    return NextResponse.json(embedData);
  } catch (error) {
    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Failed to fetch embed data' },
      { status: 500 }
    );
  }
}

Pages Router (Next.js 12 and below)

Create pages/api/embedly.ts:

import type { NextApiRequest, NextApiResponse } from 'next';
import { fetchEmbedlyData, OEmbedResponse } from '@embedly/nextjs';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<OEmbedResponse | { error: string }>
) {
  if (req.method !== 'GET') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const apiKey = process.env.EMBEDLY_API_KEY;

  if (!apiKey) {
    return res.status(500).json({ error: 'Embedly API key not configured' });
  }

  const { url, maxWidth, maxHeight } = req.query;

  if (!url || typeof url !== 'string') {
    return res.status(400).json({ error: 'URL parameter is required' });
  }

  try {
    const embedData = await fetchEmbedlyData(apiKey, {
      url,
      maxWidth: maxWidth ? parseInt(maxWidth as string, 10) : undefined,
      maxHeight: maxHeight ? parseInt(maxHeight as string, 10) : undefined,
    });

    return res.status(200).json(embedData);
  } catch (error) {
    return res.status(500).json({
      error: error instanceof Error ? error.message : 'Failed to fetch embed data',
    });
  }
}

4. Use the Component

import { EmbedlyEmbed } from '@embedly/nextjs';

export default function MyPage() {
  return (
    <div>
      <h1>Check out this video!</h1>
      <EmbedlyEmbed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />
    </div>
  );
}

API Reference

<EmbedlyEmbed />

The main React component for rendering embeds.

Props

Prop	Type	Default	Description
url	string	Required	The URL to embed
apiEndpoint	string	/api/embedly	Your Next.js API route endpoint
maxWidth	number	undefined	Maximum width for the embed
maxHeight	number	undefined	Maximum height for the embed
loading	ReactNode	Loading message	Custom loading component
error	(error: Error) => ReactNode	Error message	Custom error renderer
onLoad	(data: OEmbedResponse) => void	undefined	Callback when data loads
onError	(error: Error) => void	undefined	Callback when error occurs
className	string	undefined	Additional CSS class
style	CSSProperties	undefined	Additional inline styles

fetchEmbedlyData()

Server-side utility function for fetching OEmbed data.

async function fetchEmbedlyData(
  apiKey: string,
  options: EmbedlyFetchOptions
): Promise<OEmbedResponse>

Parameters

• apiKey: Your Embedly API key (keep this secret!)
• options.url: The URL to fetch embed data for
• options.maxWidth: (optional) Maximum width constraint
• options.maxHeight: (optional) Maximum height constraint

Examples

Basic Usage

<EmbedlyEmbed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />

Custom Loading and Error States

<EmbedlyEmbed
  url="https://vimeo.com/76979871"
  loading={<Spinner />}
  error={(err) => <ErrorMessage message={err.message} />}
/>

With Max Dimensions

<EmbedlyEmbed
  url="https://www.flickr.com/photos/example/123456789"
  maxWidth={600}
  maxHeight={400}
/>

With Callbacks

<EmbedlyEmbed
  url="https://twitter.com/username/status/123456789"
  onLoad={(data) => {
    console.log('Embed type:', data.type);
    console.log('Provider:', data.provider_name);
  }}
  onError={(err) => {
    console.error('Failed to load embed:', err);
  }}
/>

Custom Styling

<EmbedlyEmbed
  url="https://soundcloud.com/artist/track"
  className="my-embed"
  style={{
    marginTop: '2rem',
    padding: '1rem',
    border: '1px solid #ccc',
  }}
/>

Supported Platforms

Embedly supports over 1000 content providers including:

• YouTube, Vimeo, Dailymotion
• Twitter, Instagram, Facebook
• SoundCloud, Spotify
• Flickr, Imgur
• And many more!

See the full provider list.

TypeScript Support

This library is written in TypeScript and includes comprehensive type definitions:

import type {
  OEmbedResponse,
  OEmbedVideoResponse,
  OEmbedPhotoResponse,
  OEmbedRichResponse,
  OEmbedLinkResponse,
  EmbedlyFetchOptions,
} from '@embedly/nextjs';

Security

Important: Never expose your Embedly API key to the client-side. Always use it server-side in your API routes.

The library is designed with security in mind:

• API key is only used server-side
• Client component communicates through your Next.js API route
• No direct client-to-Embedly API calls

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

Library Issues & Questions

• 🐛 Bug Reports: Open an issue on GitHub
• 💬 Discussions: Start a discussion
• 🔧 Pull Requests: Contributions are welcome! See CONTRIBUTING.md

Embedly API Support

• 📧 Email: support@embed.ly
• 📚 API Documentation: docs.embed.ly/reference/embedly-api
• 🔑 Get API Key: embed.ly/signup