🔗 Extract usernames, IDs, and metadata from social media URLs across 100+ platforms.

// Turn any social media URL into structured data
parse('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
// => { platform: 'YouTube', ids: { videoId: 'dQw4w9WgXcQ' }, metadata: { contentType: 'video' } }

Installation

npm install social-link-parser
# or
yarn add social-link-parser
# or  
pnpm add social-link-parser

What It Does

This library extracts structured data from URLs across 100+ platforms. It handles all URL variations (with/without protocol, www, mobile domains, short URLs) and validates usernames according to each platform's rules.

import { parse } from 'social-link-parser'

// Extract username from any Instagram URL format
parse('instagram.com/nasa')
parse('https://www.instagram.com/nasa/')  
parse('https://www.instagram.com/p/B4uJw1qhLwV/')
parse('https://instagr.am/nasa')
// All return: { platform: 'Instagram', ids: { handle: 'nasa' } }

// Extract IDs from content URLs
parse('https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl')
// => { platform: 'Spotify', ids: { trackId: '11dFghVXANMlKmJXsNCbNl' } }

parse('https://github.com/facebook/react/pull/28797')  
// => { platform: 'GitHub', ids: { owner: 'facebook', repo: 'react', pullNumber: '28797' } }

// Validate handles
import { registry, Platforms } from 'link-parser'
const twitter = registry.get(Platforms.Twitter)!
twitter.validateHandle('jack') // => true
twitter.validateHandle('this_is_way_too_long_for_twitter') // => false

Supported Platforms (100+ total)

Instagram - Profiles, posts, stories, reels
Twitter - Profiles, tweets, spaces
TikTok - Profiles, videos
Facebook - Profiles, pages, posts, groups, events
LinkedIn - Profiles, companies, posts
Reddit - Users, subreddits, posts
Snapchat - Profiles, stories
Pinterest - Profiles, pins, boards
Tumblr - Blogs, posts
Discord - Server invites, users
Telegram - Channels, groups, users
WhatsApp - Groups, chats
VKontakte (VK) - Profiles, groups, posts
Threads - Profiles, posts
Bluesky - Profiles, posts
BeReal - Profiles
VSCO - Profiles, images
Dispo - Profiles, rolls
Clubhouse - Profiles, rooms, clubs
Medium - Profiles, publications, articles
Dev.to - Profiles, articles
Quora - Profiles, questions, spaces
StackOverflow - Users, questions
Signal - Group invites
Slack - Workspace invites

Video & Streaming (10)

YouTube - Channels, videos, playlists, shorts
Twitch - Channels, videos, clips
Vimeo - Users, videos
Dailymotion - Users, videos
Rumble - Channels, videos
Triller - Profiles, videos
BiliBili - Users, videos
BitChute - Channels, videos
Kick - Channels, videos
PeerTube - Channels, videos

Music & Audio (12)

Spotify - Artists, albums, tracks, playlists
SoundCloud - Artists, tracks, playlists
Apple Music - Artists, albums, songs
Deezer - Artists, albums, tracks
Pandora - Artists, podcasts
Tidal - Artists, albums, tracks
Bandcamp - Artists, albums, tracks
Mixcloud - Users, shows
Audiomack - Artists, songs, albums
Audius - Artists, tracks
Beatport - Artists, tracks, labels
BandLab - Users, tracks

E-commerce & Marketplace (12)

Amazon - Products, stores
Etsy - Shops, listings
eBay - Users, items
Shopify - Stores, products
Poshmark - Closets, listings
StockX - Products
Grailed - Users, listings
AliExpress - Stores, items
Wish - Products
Revolve - Products
LikeToKnowIt - Profiles, posts
ShopMy - Profiles, collections

Developer & Tech (3)

GitHub - Users, repos, issues, PRs
GitLab - Users, projects, merge requests
Bitbucket - Users, repos

Creative & Portfolio (4)

Dribbble - Users, shots
Behance - Users, projects
ArtStation - Artists, artworks
Flickr - Users, photos

Publishing & Newsletters (1)

Substack - Writers, newsletters, posts

Payment & Support (8)

PayPal - Profiles, payment links
Venmo - Profiles
CashApp - Profiles
Patreon - Creators, posts
Ko-fi - Creators, posts
BuyMeACoffee - Creators
Stripe - Payment links
Square - Checkout links

Crypto & NFT (5)

OpenSea - Collections, assets
Rarible - Users, items
LooksRare - Collections, tokens
Etherscan - Addresses, transactions
Coinbase Commerce - Checkout pages

Entertainment & Events (6)

IMDb - Titles, names
Ticketmaster - Events, artists
BandsInTown - Artists, events
Cameo - Celebrities
Fanfix - Creators
Slushy - Creators

Creator Economy & Adult Content (1)

Hoo.be - Profile links, link shortening
OnlyFans - Creator profiles

Professional & Productivity (4)

Calendly - Users, event types
Microsoft Teams - Meeting links
Matterport - Spaces
MediaKits - Profiles

Other (6)

Email - Email addresses
Phone - Phone numbers
GoFundMe - Campaigns
Stereo - Shows, creators

Key Features

Handle Validation

Each platform module knows its platform's rules:

const instagram = registry.get(Platforms.Instagram)!
instagram.validateHandle('nasa')          // ✓ valid
instagram.validateHandle('n.a.s.a')       // ✓ valid  
instagram.validateHandle('n..asa')        // ✗ consecutive dots
instagram.validateHandle('_nasa_')        // ✗ can't start/end with underscore

URL Building

Convert usernames/IDs back to canonical URLs:

const youtube = registry.get(Platforms.YouTube)!
youtube.buildProfileUrl('mkbhd')
// => 'https://www.youtube.com/@mkbhd'

youtube.buildContentUrl('video', 'dQw4w9WgXcQ')  
// => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'

URL Normalization

Clean up URLs by removing tracking parameters and fixing common issues:

parse('https://www.instagram.com/nasa/?utm_source=ig_embed')
// Returns normalized URL without tracking params

Embed Data

Get embed URLs and metadata for platforms that support embedding:

const result = parse('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
console.log(result.embedData)
// {
//   platform: 'youtube',
//   type: 'iframe',
//   contentId: 'dQw4w9WgXcQ',
//   embedUrl: 'https://www.youtube.com/embed/dQw4w9WgXcQ'
// }

// Works with Instagram, Twitter, TikTok, Spotify, SoundCloud, and more
const tweet = parse('https://twitter.com/user/status/1234567890')
console.log(tweet.embedData?.embedUrl)
// 'https://twitframe.com/show?url=...'

TypeScript Support

Full type safety with discriminated unions:

const result = parse(url)

if (result.platform === Platforms.GitHub) {
  // TypeScript knows these fields exist
  console.log(result.ids.owner, result.ids.repo)
}

API Reference

`parse(url: string): ParsedUrl`

Main parsing function that detects platform and extracts data.

`registry: Map<Platforms, PlatformModule>`

Registry of all platform modules. Use to access platform-specific methods.

`Platforms` enum

Enum of all supported platforms for type-safe platform checking.

Common Use Cases

Validate User Input

function validateSocialLink(url: string): boolean {
  const result = parse(url)
  return result.isValid && result.platform !== Platforms.Unknown
}

Extract IDs for API Calls

const result = parse('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
if (result.platform === Platforms.YouTube && result.ids.videoId) {
  // Use videoId with YouTube API
  await youtubeApi.getVideo(result.ids.videoId)
}

Build Consistent URLs

function getInstagramUrl(usernameOrUrl: string): string {
  const result = parse(usernameOrUrl)
  if (result.platform === Platforms.Instagram && result.username) {
    return `https://www.instagram.com/${result.username}`
  }
  throw new Error('Invalid Instagram URL or username')
}

Analytics & Tracking

function countLinksByPlatform(urls: string[]): Record<string, number> {
  return urls.reduce((acc, url) => {
    const { platform } = parse(url)
    if (platform && platform !== Platforms.Unknown) {
      acc[platform] = (acc[platform] || 0) + 1
    }
    return acc
  }, {})
}

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

To add a new platform, check out the Platform Implementation Guide.

License

Built with TypeScript. Tested with Jest. Used in production.

Package detail

readme

social-link-parser