#rspress-plugin-third-parties

#⚡ Overview

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.

#📑 Table of Contents

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

#📦 Installation

Install via your preferred package manager:

npm install rspress-plugin-third-parties

yarn add rspress-plugin-third-parties

pnpm add rspress-plugin-third-parties

bun add rspress-plugin-third-parties

deno add npm:rspress-plugin-third-parties

#🔌 Plugin Registration

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",
      },
    }),
  ],
});

#🧩 Component Reference

#<Script />

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>

#<Script /> Props

#<YouTubeEmbed />

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"
/>

#<YouTubeEmbed /> Props

#<GoogleMapsEmbed />

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"
/>

#<GoogleMapsEmbed /> Props

#<TweetEmbed />

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" 
/>

#<TweetEmbed /> Props

#<GoogleAnalytics />

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} />

#<GoogleAnalytics /> Props

#<GoogleTagManager />

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" }}
/>

#<GoogleTagManager /> Props

#📊 Event Tracking Utility

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>;
}

#🎯 Script Loading Strategies

#🔬 Under the Hood Mechanics

                  ┌─────────────────────────────────────────┐
                  │          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.

#📄 License

MIT © Sanjaiyan Parthipan