@flightdev/script

Script loading optimization for improved Core Web Vitals.

Installation

npm install @flightdev/script

Quick Start

import { Script } from '@flightdev/script/react';

function App() {
    return (
        <>
            <Script
                src="https://analytics.example.com/script.js"
                strategy="afterInteractive"
            />
        </>
    );
}

Loading Strategies

| Strategy | When Loaded | Use Case | |----------|-------------|----------| | beforeInteractive | Before hydration | Critical polyfills | | afterInteractive | After page is interactive | Analytics, tracking | | lazyOnload | On browser idle | Widgets, chat | | worker | In web worker | Heavy processing |

React Component

import { Script } from '@flightdev/script/react';

// External script
<Script src="https://example.com/script.js" strategy="afterInteractive" />

// Inline script
<Script id="config">
    {`window.CONFIG = { api: 'https://api.example.com' };`}
</Script>

// With callbacks
<Script
    src="https://sdk.example.com/v1.js"
    onLoad={() => window.SDK.init()}
    onError={(e) => console.error(e)}
/>

useScript Hook

import { useScript } from '@flightdev/script/react';

function Widget() {
    const { loading, loaded, error } = useScript(
        'https://widget.example.com/sdk.js',
        { strategy: 'lazyOnload' }
    );

    if (loading) return <div>Loading...</div>;
    if (error) return <div>Failed to load</div>;
    if (loaded) return <div id="widget" />;
    return null;
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | - | Script URL | | strategy | string | 'afterInteractive' | Loading strategy | | onLoad | function | - | Load callback | | onError | function | - | Error callback | | id | string | - | Script ID |

Web Worker with Partytown

Move third-party scripts to a web worker for improved INP/FID:

npm install @builder.io/partytown

Configuration

import { partytown } from '@flightdev/script/partytown';

const pt = partytown({
    debug: process.env.NODE_ENV === 'development',
    forward: ['dataLayer.push', 'gtag', 'fbq'],
    autoDetect: true, // Auto-detect common analytics domains
});

// In your HTML head
// ${pt.headSnippet}

Usage

import { Script } from '@flightdev/script/react';

// Runs in Web Worker via Partytown
<Script
    src="https://www.googletagmanager.com/gtag/js?id=G-XXX"
    strategy="worker"
/>

// Falls back gracefully if Partytown not installed

Pre-configured Domains

The autoDetect option automatically moves scripts from these domains to the worker:

• Google Analytics, Tag Manager, Ads
• Facebook Pixel, LinkedIn, Twitter
• Segment, Amplitude, Heap, Mixpanel
• Intercom, Hotjar, Mouseflow
• Sentry, LogRocket, Clarity
• And 15+ more

Partytown API

import {
    partytown,
    isPartytownReady,
    loadWithPartytown,
} from '@flightdev/script/partytown';

// Check if Partytown is available
if (isPartytownReady()) {
    // Partytown is loaded
}

// Load a script with Partytown (falls back if unavailable)
await loadWithPartytown('https://example.com/script.js');

License

MIT