@atlas-parthenon/sdk-nextjs
v0.1.0-alpha.1
Published
Next.js helpers for Atlas machine-authenticated telemetry.
Maintainers
amsheehanReadme
@atlas-parthenon/sdk-nextjs
Next.js helpers for Atlas machine-authenticated telemetry.
What it does
- reuses the installation-authenticated Node.js transport on the server
- exposes one small browser client that forwards events to a local Next.js route
- starts a real browser session on first activity and closes it on page hide so Atlas can list ended sessions
- gives Next.js apps a simple server-operation wrapper for logs, exceptions, and duration metrics
Typical shape
import {
AtlasNextErrorMonitor,
createBrowserIngestRoute,
createInstrumentedFetch,
instrumentNextServerOperation
} from "@atlas-parthenon/sdk-nextjs";- use
instrumentNextServerOperation()around Server Actions or Route Handlers - use
createInstrumentedFetch()when you want a wrapped server-sidefetch - use
createBrowserIngestRoute()inside an app-local API route such as/api/atlas/browser - mount
AtlasNextErrorMonitoronce in your root layout if you want window error, unhandled-rejection, and browser session lifecycle capture
Integration Pattern
Keep the SDK generic and put app-specific naming in the app:
- SDK responsibility:
- transport
- browser forwarding
- generic operation/fetch instrumentation
- app responsibility:
- operation names
- attrs
- which routes, actions, and fetches to instrument
The older names remain exported for compatibility:
withAtlasNextServerSpan()createAtlasNextBrowserEndpoint()AtlasNextClientBootstrap
Config
Server helpers read the same install credentials as @atlas-parthenon/sdk-nodejs:
ATLAS_INGEST_BASE_URLATLAS_INSTALLATION_IDATLAS_INSTALLATION_SECRETATLAS_SERVICE_NAMEorATLAS_FIXTURE_SERVICE_NAME
Optional enrichment:
ATLAS_SERVICE_NAMESPACEATLAS_SERVICE_VERSIONATLAS_DEPLOYMENT_ENVIRONMENTATLAS_RELEASE_VERSIONATLAS_REPOATLAS_COMMIT_SHA
Minimal browser setup
// app/api/atlas/browser/route.ts
import { createBrowserIngestRoute } from "@atlas-parthenon/sdk-nextjs";
export const POST = createBrowserIngestRoute();// app/layout.tsx
import { AtlasNextClientBootstrap } from "@atlas-parthenon/sdk-nextjs";
export default function RootLayout({
children
}: Readonly<{ children: React.ReactNode }>) {
return (
<html lang="en">
<body>
<AtlasNextClientBootstrap endpoint="/api/atlas/browser" />
{children}
</body>
</html>
);
}Once deployed, the browser client writes a started event the first time it
captures activity, increments a per-session error count on exceptions, and
writes an ended event when the page is hidden or unloaded. Atlas can then
group those events into ended browser sessions.
Publishing
Atlas maintainers can verify and package both SDKs from the repo root with:
pnpm sdk:checkThat script typechecks, tests, rebuilds, packs, and validates the npm tarballs before any publish step.