npm package: @flightdev/script
Description: Agnostic script loading optimization with multiple strategies
Latest version: 0.0.3

# @flightdev/script

Script loading optimization for improved Core Web Vitals.

## Installation

```bash
npm install @flightdev/script
```

## Quick Start

```tsx
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

```tsx
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

```tsx
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:

```bash
npm install @builder.io/partytown
```

### Configuration

```typescript
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

```tsx
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

```typescript
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