@harnessa-fe/next
Advanced tools
Next.js integration for Harnessa-FE. Drop-in <HarnessaScript /> server component that loads the runtime client and seeds window config — no webpack hooks, no SWC plugin, works with App Router + Pages Router + webpack + Turbopack.
Next.js integration for Harnessa-FE. Drop-in Server Component + config wrapper. Works with App Router + Pages Router, webpack + Turbopack, Node + Edge runtime.
pnpm add -D @harnessa-fe/next @harnessa-fe/react-jsx @harnessa-fe/runtime @harnessa-fe/node-runtime
<HarnessaScript /> — boots the runtime client in the browser AND auto-registers @harnessa-fe/node-runtime on first server render (no instrumentation.ts boilerplate).getSessionId() — React cache()-backed, request-scoped UUID. Same id reused across every Server Component, Route Handler, and Server Action in one request, and seeded into the HTML so the browser client adopts it.withHarnessa() — wraps next.config.mjs to inject the auto-boot import into the server bundle (alternative path for projects that don't render <HarnessaScript> at the root).1. tsconfig.json — enable source-tagging JSX runtime so agents can locate elements:
{
"compilerOptions": {
"jsxImportSource": "@harnessa-fe/react-jsx"
}
}
2. next.config.mjs — (optional, alternative to <HarnessaScript>):
import { withHarnessa } from '@harnessa-fe/next/config';
const nextConfig = { /* …your config… */ };
export default withHarnessa(nextConfig, { projectId: 'my-app' });
3. app/layout.tsx — Server Component, no 'use client' needed:
import { HarnessaScript } from '@harnessa-fe/next';
export default async function RootLayout({ children }) {
return (
<html>
<body>
<HarnessaScript
projectId="my-app"
userId={someUser?.id}
buildId={process.env.NEXT_PUBLIC_GIT_SHA}
/>
{children}
</body>
</html>
);
}
4. Start the daemon (pnpm exec @harnessa-fe/mcp-server or any installed binary) then pnpm dev. Two peer connected lines should appear in the daemon log per refresh — one role=node-runtime, one role=runtime-client, same sessionId.
<HarnessaScript /> props| Prop | Type | Default | Notes |
|---|---|---|---|
projectId | string (required) | — | Stable id for the codebase; agents key off this |
displayName | string | projectId | Human-readable label shown in agent UIs |
userId | string? | — | App-supplied user id; daemon-local, never leaves your machine |
buildId | string? | — | Build artifact id (e.g. process.env.NEXT_PUBLIC_GIT_SHA) |
parentProjectId | string? | — | Set when this app is hosted inside another via iframe / module federation |
mcpUrl | string? | ws://127.0.0.1:47729 | Daemon WebSocket URL |
In production (NODE_ENV !== 'development') <HarnessaScript> renders null and pulls no code into client bundles.
This is the value-add over a plain pair of "server SDK + browser SDK":
request arrives
│
▼
<HarnessaScript> renders (Server Component)
│ ├─ ensureNodeRuntimeBooted() ─ registers @harnessa-fe/node-runtime once per process
│ ├─ import('./sessionId.js') ─ side-effect: setSessionIdProvider(getSessionId)
│ └─ getSessionId() ────────────► React cache() allocates sid-X for this render
│ │
│ ▼
▼ server-side console.log
seed <script>window.__HARNESSA_FE_SEED__={sessionId:'sid-X'} │
▼
node-runtime
.getRequestSessionId()
reads provider → 'sid-X'
▼
server-log event { sessionId: 'sid-X' }
HTML reaches browser
│
▼
<HarnessaScriptClient> hydrates
└─ reads window.__HARNESSA_FE_SEED__ → adopts sid-X
│
▼
client console.log / log.info
→ app-log event { sessionId: 'sid-X' }
Result: one refresh = one sessions/{sid-X}/timeline.jsonl containing both server and client events. No bookkeeping in user code.
<HarnessaScript> detects process.env.NEXT_RUNTIME === 'edge' and loads @harnessa-fe/node-runtime/auto-edge instead of the WebSocket-based main entry. Edge requests post events to the daemon over HTTP-batch (POST /events) since Edge can't keep a long-lived WS or call process.on. Same sessionId, same timeline.
<HarnessaScript>Two paths to register the Node SDK:
<HarnessaScript> | withHarnessa() | |
|---|---|---|
| Where it boots | First server render | Server bundle entry-point |
| Required for SSR-less routes (Route Handlers only) | No | Yes |
| Works with Turbopack | ✅ (no bundler plugin) | ⚠️ webpack only |
| Recommended | Yes, for almost everyone | Use if you have Route Handlers but no rendered pages |
You can use both at once; register() is idempotent.
// @harnessa-fe/next
export { HarnessaScript, type HarnessaScriptProps };
export { getSessionId };
// @harnessa-fe/next/config
export { withHarnessa, type WithHarnessaOptions };
// @harnessa-fe/next/sessionId
export const getSessionId: () => string; // React cache()-backed
Inlined script in the body, runs before hydration:
<script id="__hfe_seed__">window.__HARNESSA_FE_SEED__={"sessionId":"01HM..."};</script>
The runtime client reads this at DOMContentLoaded and adopts the id instead of generating a fresh UUID — that's how server and client end up with the same sessionId.
MIT
FAQs
Next.js integration for Harnessa-FE. Drop-in <HarnessaScript /> server component that loads the runtime client and seeds window config — no webpack hooks, no SWC plugin, works with App Router + Pages Router + webpack + Turbopack.
We found that @harnessa-fe/next demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm invalidated all granular access tokens that bypass 2FA after a fresh Mini Shai-Hulud wave compromised 323 npm packages. Staged publishing also entered public preview.
Research
/Security News
Compromised npm package art-template delivered a Coruna-like iOS Safari exploit framework through a watering-hole attack.
Company News
As AI accelerates how code is written and shipped, Socket is scaling to protect the software supply chain from the growing wave of attacks targeting open source dependencies.