Async Script Loader

A lightweight TypeScript library for dynamically loading external JavaScript files with promise-based API and automatic timeout handling.

Features

- Promise-based API for script loading
- Automatic timeout handling (2 second default)
- Proper event listener cleanup to prevent memory leaks
- URL encoding for query parameters
- TypeScript support with full type definitions
- Works in both ES modules and browser environments
- Small bundle size (~1 KB)

Why not use import()?

This library is not a replacement for the native import() function. They serve different purposes:

Use import() when:
- Loading ES modules with exports you need to access
- Working with your own modular code
- You need tree-shaking and modern module features

Use this library when:
- Loading third-party scripts that aren't ES modules (analytics, ads, legacy libraries)
- Scripts that set global variables or have side effects
- You need to append query parameters to the script URL
- Loading scripts that don't have exports (just execute code)
- You need timeout handling for unreliable external scripts
- Working with scripts designed to be loaded via







`

$3

The library includes TypeScript definitions out of the box:

`typescript
import { asyncScriptLoader } from '@zoltanradics/async-script-loader';

const loadScript = async (): Promise => {
try {
await asyncScriptLoader('https://api.example.com/sdk.js', {
version: '2.0',
debug: 'true'
});
// Script loaded successfully
} catch (error) {
// Handle error
console.error(error);
}
};

loadScript();
`

API

$3

Dynamically injects a script tag into the document head and returns a Promise.

#### Parameters

- baseUrl (string): The base URL of the script to load
- queryParamObject (object): An object containing query parameters to append to the URL
- Keys and values will be automatically URL-encoded
- Example: { key: 'value', foo: 'bar' } becomes ?key=value&foo=bar

#### Returns

- Promise: Resolves when the script loads successfully, rejects on error or timeout

#### Behavior

- The script is injected into the element with async attribute
- Automatically times out after 2 seconds if the script hasn't loaded
- On timeout, the promise resolves (not rejects) with a console warning
- On error, the promise rejects with an error message
- Event listeners are automatically cleaned up after load/error/timeout

Examples

$3

`javascript
import { asyncScriptLoader } from '@zoltanradics/async-script-loader';

asyncScriptLoader('https://www.googletagmanager.com/gtag/js', {
id: 'G-XXXXXXXXXX'
})
.then(() => {
window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
});
`

$3

`javascript
import { asyncScriptLoader } from '@zoltanradics/async-script-loader';

async function loadScripts() {
try {
await asyncScriptLoader('https://cdn.example.com/library.js', {});
console.log('Library loaded');

await asyncScriptLoader('https://cdn.example.com/plugin.js', {
theme: 'dark'
});
console.log('Plugin loaded');

// Both scripts are now loaded
} catch (error) {
console.error('Script loading failed:', error);
}
}

loadScripts();
`

$3

`javascript
import { asyncScriptLoader } from '@zoltanradics/async-script-loader';

Promise.all([
asyncScriptLoader('https://cdn.example.com/script1.js', {}),
asyncScriptLoader('https://cdn.example.com/script2.js', {}),
asyncScriptLoader('https://cdn.example.com/script3.js', {})
])
.then(() => {
console.log('All scripts loaded successfully');
})
.catch((error) => {
console.error('One or more scripts failed to load:', error);
});
`

Development

`bash


Install dependencies

npm install

Start development server

npm run dev

Build for production

npm run build

Preview production build

npm run preview
``

License

MIT © Zoltan Radics

Made with ❤️ by Zoltan Radics