High-performance third-party embeds, Google Tag Manager, analytics, and non-blocking script strategies for Rspress sites.

📖 Read the Documentation · 🚀 View Interactive Demo · 📦 NPM Package

rspress-plugin-third-parties brings Next.js-style third-party optimizations (@next/third-parties) directly to Rspress.

External embeds (like YouTube, Google Maps, and Twitter/X posts) and script tags (like GA4 and GTM) are notorious for blocking the main thread, lowering Lighthouse performance scores, and causing layout shifts. This plugin solves that by providing:

• ⚡ React Compiler Pre-Optimized: Ships fully compiled with automated auto-memoization at build-time. Zero unnecessary re-renders.
• 🚀 Non-Blocking Execution: Lazy loading scripts using requestIdleCallback and fine-grained loading strategies.
• ⚡ React 19 Resource Pre-initialization: Leverages native ReactDOM.preinit and ReactDOM.preload during SSG/SSR.
• 🧠 Smart Memory Caching: Built-in script deduplication and stylesheet cache registry.
• 🛠️ Zero-Config Global GA: Inject Google Analytics across all documentation pages automatically via your rspress.config.ts.
• 📦 Zero-Weight Embeds: Powered by third-party-capital for lightweight HTML generation.

• Installation
• Plugin Registration
• Component Reference
  • <Script />
  • <YouTubeEmbed />
  • <GoogleMapsEmbed />
  • <TweetEmbed />
  • <GoogleAnalytics />
  • <GoogleTagManager />
• Event Tracking Utility
• Script Loading Strategies
• Under the Hood Mechanics
• License

Install via your preferred package manager:

# pnpm
pnpm add rspress-plugin-third-parties

# npm
npm install rspress-plugin-third-parties

# yarn
yarn add rspress-plugin-third-parties

To auto-inject Google Analytics globally across your Rspress documentation, register the plugin in your rspress.config.ts:

// rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginThirdParties } from 'rspress-plugin-third-parties/plugin';

export default defineConfig({
  plugins: [
    pluginThirdParties({
      googleAnalytics: {
        gaId: 'G-XXXXXXXXXX', // Your GA4 Measurement ID
        debugMode: false, // Set to true for local testing
        dataLayerName: 'dataLayer',
      },
    }),
  ],
});

Source code

The foundation component powering all external integrations. It manages script mounting, deduplication, inline scripts, stylesheet preloading, and lifecycle events (onLoad, onReady, onError).

import { Script } from 'rspress-plugin-third-parties';

{/* Load after interactive */}

<Script
  src="https://sanjaiyan-cool.web.app/script/v1/1/SanWebMaker.js"
  strategy="afterInteractive"
  onLoad={() => console.log('Widgets loaded!')}
/>

{/* Inline Script */}
<Script id="custom-inline-script">
  {`console.log('Inline script running');`}
</Script>

Source code

Powered by lite-youtube-embed under the hood. Renders an ultra-fast visual facade that defers the heavy YouTube player until play is clicked—keeping your main thread pristine and Lighthouse scores flawless.

import { YouTubeEmbed } from 'rspress-plugin-third-parties';

# Youtube Video

<YouTubeEmbed
  videoid="sSbDtQTtwBY"
  height={400}
  playlabel="A Lineage of Logic, A Future of Code"
/>

Source code

Provides performance-optimized embeds for Google Maps without blocking the browser during initial navigation.

import { GoogleMapsEmbed } from 'rspress-plugin-third-parties';

<GoogleMapsEmbed
  apiKey="YOUR_GOOGLE_MAPS_API_KEY"
  mode="place"
  q="Point Pedro, Sri Lanka"
  height={450}
  zoom="14"
/>

Source code

Zero-overhead Twitter/X post embed powered by react-tweet. Fetches raw post data and renders lightweight, native React DOM components styled identically to X/Twitter UI without downloading heavy widgets.js scripts or layout-shifting IFrames.

import { TweetEmbed } from 'rspress-plugin-third-parties';

{/* Basic Tweet */}

<TweetEmbed id="2017178323550605790" />

{/* Tweet with optional forced theme */}

<TweetEmbed id="2017178323550605790" theme="dark" />

Source code

Explicitly embed Google Analytics 4 (GA4) inside MDX pages or custom layout components.

import { GoogleAnalytics } from 'rspress-plugin-third-parties';

<GoogleAnalytics gaId="G-XXXXXXXXXX" debugMode={true} />

Source code

Integrate Google Tag Manager (GTM) with support for custom domains, authentication, preview environments, and custom initial dataLayer states.

import { GoogleTagManager } from 'rspress-plugin-third-parties';

<GoogleTagManager
  gtmId="GTM-XXXXXXX"
  dataLayer={{ userRole: 'developer', env: 'production' }}
/>

Send custom Google Analytics events dynamically from anywhere in your client-side React code:

import { sendGAEvent } from 'rspress-plugin-third-parties';

function FeedbackButton() {
  const handleClick = () => {
    sendGAEvent('event', 'documentation_helpful', {
      page: window.location.pathname,
      vote: 'yes',
    });
  };

  return <button onClick={handleClick}>Helpful 👍</button>;
}

                  ┌─────────────────────────────────────────┐
                  │          Rspress SSG Build Phase        │
                  └────────────────────┬────────────────────┘
                                       │
                  ┌────────────────────▼────────────────────┐
                  │      Server Pre-render Execution        │
                  │   Calls safePreload() & safePreinit()   │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                     HTML Output with Native Preloads
                                       │
                  ┌────────────────────▼────────────────────┐
                  │        Hydration & Browser Idle         │
                  └────────────────────┬────────────────────┘
                                       │
             ┌─────────────────────────┼─────────────────────────┐
             │                         │                         │
             ▼                         ▼                         ▼
   [afterInteractive]           [lazyOnload]           [Cache Deduplication]
   Appends script after     Uses requestIdleCallback     Prevents fetching identical
   client hydration.        to minimize TBT.             `src`/`id` entries twice.

1. React 19 Resource Pre-init: Uses ReactDOM.preinit and ReactDOM.preload to declare external resource hints before browser parsing.
2. Script Caching: Maintains global ScriptCache and LoadCache Map/Set singletons, ensuring identical script tags are never loaded twice across page transitions.
3. Graceful React 18 Fallback: Fallbacks to dynamic document.createElement('link') stylesheet injection when React 19 resource pre-init functions are unavailable.

Run these commands from the monorepo root:

pnpm install
pnpm --filter rspress-plugin-third-parties build
pnpm exec playwright install chromium
pnpm e2e rspress-plugin-third-parties
pnpm lint
pnpm --filter rspress-plugin-third-parties docs:build
pnpm --filter rspress-plugin-third-parties docs:dev

The package uses the shared Rstack toolchain, TypeScript configuration, and pnpm catalog. It publishes ESM components and a separate Node.js plugin entry. Playwright tests run alongside the other plugins through the root pnpm e2e command. Versioning and publishing use the root Changesets configuration.

MIT © Sanjaiyan Parthipan and the Rspress Community (from September 2026 onward)