react-tweet

react-tweet is a Vercel-maintained library that embeds live tweets in a React application without loading Twitter’s widgets.js script or wrapping content in an iframe. It calls Twitter’s public syndication API directly and renders the result with its own from-scratch Twitter-themed components — avatars, verified badges, quoted tweets, media galleries, and action buttons — so the rendered markup, styling, and caching behavior stay fully under the consuming app’s control.

The same react-tweet import resolves to two different implementations depending on the bundler’s module conditions: React Server Component environments (Next.js app router) get an async, Suspense-wrapped Tweet component that fetches data at render time, while everything else falls back to a client component that fetches via SWR and can be pointed at a custom apiUrl for teams proxying requests through their own backend. A separate react-tweet/api subpath exposes the underlying getTweet/fetchTweet functions directly for anyone who wants the raw tweet JSON without the bundled UI.

What You Get

• A pre-styled EmbeddedTweet UI (avatars, verified badges, quoted tweets, media, reply/like counts) matching Twitter’s own look
• A dual server/client Tweet component that auto-selects an async RSC-friendly implementation or an SWR-backed client implementation based on the bundler’s module conditions
• A standalone react-tweet/api subpath exposing getTweet/fetchTweet for fetching raw tweet JSON without any UI
• A theme.css stylesheet you can import directly, plus a components prop for swapping in your own TweetNotFound/TweetSkeleton overrides
• Built-in tombstone/deleted-tweet and not-found handling with dedicated fallback components

Common Use Cases

• Blog and docs embeds - technical writers drop a tweet ID into MDX/Markdown content to embed a live, styled tweet without shipping Twitter’s widgets.js bundle.
• Server-rendered marketing pages - Next.js app router sites render tweets at build/request time via the RSC-aware Tweet component, avoiding client-side loading flicker.
• Custom tweet proxies - teams route tweet fetches through their own backend by passing a custom apiUrl to the client Tweet component, adding caching or rate-limit protection in front of Twitter’s syndication endpoint.
• Headless tweet data - apps that want tweet content but not Twitter’s visual chrome import react-tweet/api directly and render the JSON with their own components.

Under The Hood

Architecture

The package separates concerns cleanly across three layers: a typed data layer (src/api/) that talks to Twitter’s syndication API (fetch-tweet.ts, get-tweet.ts, get-oembed.ts) and defines the full tweet shape across seven type files (tweet.ts, user.ts, media.ts, photo.ts, video.ts, entities.ts, edit.ts); a presentational layer (src/twitter-theme/) of small, single-responsibility components (tweet-header.tsx, tweet-body.tsx, tweet-media.tsx, quoted-tweet/, icons/) each paired with a CSS module; and a thin composition layer at the root (tweet.tsx, swr.tsx, hooks.ts) that wires data to presentation. The most notable architectural choice is the dual entry point: index.ts exports an async, Suspense-wrapped server component selected via the package.json react-server export condition, while index.client.ts exports an SWR-driven client component as the fallback for bundlers that don’t understand RSC conditions — both converge on the same EmbeddedTweet presentational tree, so swapping data-fetching strategy never touches rendering code. If the syndication API’s response shape changed, the blast radius would stay contained to src/api/types/ and the two fetcher files, since components consume only the typed Tweet/QuotedTweet interfaces.

Tech Stack

Written in TypeScript and compiled via @swc/core/@swc/cli rather than tsc for the JS output, with a separate tsc --emitDeclarationOnly pass just for .d.ts files, orchestrated at the monorepo level by Turborepo and pnpm workspaces. Runtime dependencies are deliberately minimal — swr for client-side data fetching/caching, clsx for conditional class names, and @swc/helpers for compiled output — with react/react-dom kept as peer dependencies only. There’s no separate bundler config for the library itself; SWC handles transpilation and copies CSS Modules alongside compiled JS. Releases are automated via Changesets and a GitHub Actions release workflow that runs on every push to main. The monorepo also bundles demo/docs applications used for manual verification rather than automated testing.

Code Quality

No test files exist anywhere in the repository — correctness is verified manually through the bundled demo apps rather than an automated suite. Type safety is otherwise strong: every data shape has a dedicated interface under src/api/types/, and the fetch layer returns typed unions rather than throwing for expected failure modes. Error handling is deliberate rather than swallowed: the fetcher throws a custom, status-carrying error class for genuine failures, while distinguishing tombstoned/private tweets and not-found responses as typed, non-throwing states, with the higher-level API logging a specific message for each case. Naming is consistent and self-documenting across the fetch/data/hook layers. Linting runs through ESLint extending a shared config, though CI only runs the release workflow — there’s no separate lint/typecheck/test gate visible in the repository’s workflows.

API Design The public API is small and deliberately symmetric: a single Tweet component import works identically whether the consuming app is an RSC-capable app-router project or a plain client-rendered app, because the package’s export map silently selects the right implementation — consumers never branch on environment themselves. Getting started requires exactly one import and one required prop; everything else is optional with sensible defaults, including a built-in loading skeleton and not-found fallback. A lightweight component-override prop enables partial customization without needing to fork or wrap the whole tree. The one rough edge is documentation: the package’s own README is a brief pointer to an external docs site rather than a self-contained API reference, so anyone reading only the GitHub repo has to cross-reference the component prop types directly to discover the full surface area.