heimdall-sdk
v0.2.1
Published
Heimdall SDK — zero-config API logger for React
Downloads
31
Readme
heimdall-sdk
Zero-config API logger for React (and any JS framework).
The Heimdall SDK automatically intercepts every fetch and XMLHttpRequest call in your frontend and sends the logs to a Heimdall server, where you can browse them in a dashboard.
Requirements
A running Heimdall server. The easiest way is Docker:
docker run -d \
--name heimdall \
-p 3333:3333 \
-v heimdall_data:/data \
ghcr.io/alessandroamormino/heimdall:latestSee the full server setup guide.
Installation
npm install heimdall-sdkUsage
React
// main.tsx or App.tsx
import { HeimdallProvider } from 'heimdall-sdk'
export default function App() {
return (
<HeimdallProvider collectorUrl="http://localhost:3333">
<YourApp />
</HeimdallProvider>
)
}That's it. Every fetch and XHR call is now logged automatically.
Next.js
// app/layout.tsx
import { HeimdallProvider } from 'heimdall-sdk'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<HeimdallProvider collectorUrl="http://localhost:3333">
{children}
</HeimdallProvider>
</body>
</html>
)
}Add
'use client'at the top if Next.js requires it.
Vue / Svelte / Vanilla JS
import { patchFetch } from 'heimdall-sdk'
patchFetch({
collectorUrl: 'http://localhost:3333',
project: 'my-app',
})Options
| Prop | Type | Default | Description |
|---|---|---|---|
| collectorUrl | string | — | Required. URL of the Heimdall server |
| project | string | "default" | Label to group logs by app |
| ignore | (string \| RegExp)[] | [] | URLs to skip (matched by substring or regex) |
| enabled | boolean | true | Set to false to disable interception |
<HeimdallProvider
collectorUrl="http://localhost:3333"
project="my-app"
ignore={['/health', /^\/internal/]}
enabled={process.env.NODE_ENV !== 'production'}
>Secret detection
The SDK automatically scans every request for exposed secrets before sending the log. If a token or credential is found, its value is replaced with [REDACTED] and a warning is recorded.
| Location | Examples |
|---|---|
| URL query parameters | access_token, api_key, token, secret, password, … |
| Request headers | Authorization, x-api-key, x-auth-token, Cookie, … |
| Token-shaped values | JWT (eyJ…), Mapbox (sk./pk.), long hex/base64 strings |
The real token never reaches the server or the database — redaction happens entirely in the browser.
License
MIT — © Alessandro Amormino