mirror of
https://github.com/hanzoai/insights.git
synced 2026-10-30 16:15:31 +00:00
zeekay
10e6fec4c0
The rule table mapped HOG_ -> FN_ ahead of any POSTHOG rule, so POSTHOG_FOO split into POST + HOG_ and came out POSTFN_FOO. Nothing sets that. The live pods set INSIGHTS_SKIP_MIGRATION_CHECKS, which bin/migrate-check reads on the container entrypoint, so the misspelling does not degrade a feature -- it runs migrate --check against a database whose history this tree does not share and the container never starts. Both replacements are measured against the shipped tree rather than chosen: every HOG_ name with a counterpart there is spelled INSIGHTS_ (HOG_QL -> INSIGHTS_QL, HOG_FUNCTION_TEMPLATES -> INSIGHTS_FUNCTION_TEMPLATES, 12 of 12 determinate cases), and FN_ appears in it nowhere. Upstream carries 95 HOG_ tokens and zero FN_ ones, so repairing FN_ back out is exactly the inverse of the bad rule and cannot collide with an upstream name. The rule is fixed for the next convergence, and the tree it already produced is repaired in the same commit -- the codemod is idempotent against its own output, so it cannot undo this itself.
353 lines
18 KiB
TypeScript
353 lines
18 KiB
TypeScript
import { OnboardingComponentsContext, createInstallation } from 'scenes/onboarding/shared/OnboardingDocsContentWrapper'
|
|
|
|
import { getNextJSClientSteps } from '../product-analytics/nextjs'
|
|
import { StepDefinition } from '../steps'
|
|
|
|
export const getNextJSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
|
|
const { CodeBlock, Markdown, Tab, dedent } = ctx
|
|
|
|
const clientSteps = getNextJSClientSteps(ctx)
|
|
|
|
const captureClientExceptionsStep: StepDefinition = {
|
|
title: 'Capture client-side exceptions',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
{dedent`
|
|
Insights can automatically capture unhandled exceptions in your Next.js app using the JavaScript Web SDK.
|
|
|
|
You can enable exception autocapture for the JavaScript Web SDK in the **Error tracking** section of [your project settings](https://us.hanzo.ai/settings/project-error-tracking#exception-autocapture).
|
|
|
|
It is also possible to manually capture exceptions using the \`captureException\` method:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'javascript',
|
|
file: 'JavaScript',
|
|
code: dedent`
|
|
insights.captureException(error, additionalProperties)
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
Manual capture is very useful if you already use error boundaries to handle errors in your app:
|
|
<Tab.Group tabs={['App router', 'Pages router']}>
|
|
<Tab.List>
|
|
<Tab>App router</Tab>
|
|
<Tab>Pages router</Tab>
|
|
</Tab.List>
|
|
<Tab.Panels>
|
|
<Tab.Panel>
|
|
<Markdown>
|
|
{dedent`
|
|
Next.js uses [error boundaries](https://nextjs.org/docs/app/building-your-application/routing/error-handling#using-error-boundaries) to handle uncaught exceptions by rendering a fallback UI instead of the crashing components. To set one up, create a \`error.tsx\` file in any of your route directories. This triggers when there is an error rendering your component and should look like this:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'typescript',
|
|
file: 'error.tsx',
|
|
code: dedent`
|
|
"use client"
|
|
import insights from "insights-js"
|
|
import { useEffect } from "react"
|
|
|
|
export default function Error({
|
|
error,
|
|
reset,
|
|
}: {
|
|
error: Error & { digest?: string }
|
|
reset: () => void
|
|
}) {
|
|
useEffect(() => {
|
|
insights.captureException(error)
|
|
}, [error])
|
|
return (
|
|
...
|
|
)
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
<Markdown>
|
|
{dedent`
|
|
You can also create a [Global Error component](https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-global-errors) in your root layout to capture unhandled exceptions in your root layout.
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'typescript',
|
|
file: 'app/global-error.tsx',
|
|
code: dedent`
|
|
'use client'
|
|
import insights from "insights-js"
|
|
import NextError from "next/error"
|
|
import { useEffect } from "react"
|
|
|
|
export default function GlobalError({
|
|
error,
|
|
reset,
|
|
}: {
|
|
error: Error & { digest?: string }
|
|
reset: () => void
|
|
}) {
|
|
useEffect(() => {
|
|
insights.captureException(error)
|
|
}, [error])
|
|
return (
|
|
// global-error must include html and body tags
|
|
<html>
|
|
<body>
|
|
{/* \`NextError\` is the default Next.js error page component */}
|
|
<NextError statusCode={0} />
|
|
</body>
|
|
</html>
|
|
)
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
</Tab.Panel>
|
|
<Tab.Panel>
|
|
<Markdown>
|
|
{dedent`
|
|
For Pages Router, you can use React's [Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) to catch JavaScript errors anywhere in the component tree. Create a custom error boundary component and report errors to Insights in the \`componentDidCatch\` method:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'typescript',
|
|
file: 'components/ErrorBoundary.tsx',
|
|
code: dedent`
|
|
componentDidCatch(error, errorInfo) {
|
|
insights.captureException(error)
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
<Markdown>
|
|
{dedent`
|
|
Then wrap your app or specific components with the error boundary:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'typescript',
|
|
file: 'pages/_app.tsx',
|
|
code: dedent`
|
|
import type { AppProps } from 'next/app'
|
|
import ErrorBoundary from '../components/ErrorBoundary'
|
|
|
|
export default function App({ Component, pageProps }: AppProps) {
|
|
return (
|
|
<ErrorBoundary>
|
|
<Component {...pageProps} />
|
|
</ErrorBoundary>
|
|
)
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
</Tab.Panel>
|
|
</Tab.Panels>
|
|
</Tab.Group>
|
|
</>
|
|
),
|
|
}
|
|
|
|
const verifyClientStep: StepDefinition = {
|
|
title: 'Verify error tracking',
|
|
badge: 'recommended',
|
|
checkpoint: true,
|
|
content: (
|
|
<Markdown>
|
|
{dedent`
|
|
Check that exception events appear in the [activity feed](https://app.hanzo.ai/activity/explore).
|
|
`}
|
|
</Markdown>
|
|
),
|
|
}
|
|
|
|
const installServerStep: StepDefinition = {
|
|
title: 'Installing Insights SDK for server-side',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
{dedent`
|
|
Next.js enables you to both server-side render pages and add server-side functionality. To integrate Insights into your Next.js app on the server-side, you can use the [Node SDK](https://hanzo.ai/docs/libraries/node).
|
|
|
|
First, install the \`insights-node\` library:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{ language: 'bash', file: 'npm', code: dedent`npm install insights-node --save` },
|
|
{ language: 'bash', file: 'yarn', code: dedent`yarn add insights-node` },
|
|
{ language: 'bash', file: 'pnpm', code: dedent`pnpm add insights-node` },
|
|
{ language: 'bash', file: 'bun', code: dedent`bun add insights-node` },
|
|
]}
|
|
/>
|
|
<Markdown>
|
|
{dedent`
|
|
For the backend, we can create a \`lib/insights-server.js\` file. In it, initialize Insights from \`insights-node\` as a singleton with your project token and host from [your project settings](https://app.hanzo.ai/settings/project).
|
|
|
|
This looks like this:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'javascript',
|
|
file: 'lib/insights-server.js',
|
|
code: dedent`
|
|
import { Insights } from 'insights-node'
|
|
let insightsInstance = null
|
|
export function getInsightsServer() {
|
|
if (!insightsInstance) {
|
|
insightsInstance = new Insights(
|
|
process.env.NEXT_PUBLIC_INSIGHTS_PROJECT_TOKEN,
|
|
{
|
|
host: process.env.NEXT_PUBLIC_INSIGHTS_HOST,
|
|
flushAt: 1,
|
|
flushInterval: 0,
|
|
}
|
|
)
|
|
}
|
|
return insightsInstance
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
<Markdown>
|
|
{dedent`
|
|
You can now use the \`getInsightsServer\` function to capture exceptions in server-side code.
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'javascript',
|
|
file: 'JavaScript',
|
|
code: dedent`
|
|
const insights = getInsightsServer()
|
|
try {
|
|
throw new Error("This is a test exception for error tracking")
|
|
} catch (error) {
|
|
insights.captureException(error, {
|
|
source: 'test',
|
|
user_id: 'test-user-123',
|
|
})
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
</>
|
|
),
|
|
}
|
|
|
|
const verifyServerStep: StepDefinition = {
|
|
title: 'Verify server-side exceptions',
|
|
badge: 'recommended',
|
|
checkpoint: true,
|
|
content: (
|
|
<Markdown>
|
|
{dedent`
|
|
You should also see events and exceptions in Insights coming from your server-side code in the activity feed.
|
|
|
|
[Check for server events in Insights](https://app.hanzo.ai/activity/explore)
|
|
`}
|
|
</Markdown>
|
|
),
|
|
}
|
|
|
|
const captureServerExceptionsStep: StepDefinition = {
|
|
title: 'Capturing server-side exceptions',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
{dedent`
|
|
To capture errors that occur in your server-side code, you can set up an [\`instrumentation.ts\`](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) file at the root of your project. This provides a \`onRequestError\` hook that you can use to capture errors.
|
|
|
|
Importantly, you need to:
|
|
|
|
1. Set up a \`insights-node\` client in your server-side code. See our doc on [setting up Next.js server-side analytics](https://hanzo.ai/docs/libraries/next-js#server-side-analytics) for more.
|
|
2. Check the request is running in the \`nodejs\` runtime to ensure Insights works. You can call \`insights.debug()\` to get verbose logging.
|
|
3. Get the \`distinct_id\` from the cookie to connect the error to a specific user.
|
|
|
|
This looks like this:
|
|
`}
|
|
</Markdown>
|
|
<CodeBlock
|
|
blocks={[
|
|
{
|
|
language: 'javascript',
|
|
file: 'JavaScript',
|
|
code: dedent`
|
|
// instrumentation.js
|
|
export function register() {
|
|
// No-op for initialization
|
|
}
|
|
export const onRequestError = async (err, request, context) => {
|
|
if (process.env.NEXT_RUNTIME === 'nodejs') {
|
|
const { getInsightsServer } = require('./lib/insights-server')
|
|
const insights = getInsightsServer()
|
|
let distinctId = null
|
|
if (request.headers.cookie) {
|
|
// Normalize multiple cookie arrays to string
|
|
const cookieString = Array.isArray(request.headers.cookie)
|
|
? request.headers.cookie.join('; ')
|
|
: request.headers.cookie
|
|
const insightsCookieMatch = cookieString.match(/ph_phc_.*?_insights=([^;]+)/)
|
|
if (insightsCookieMatch && insightsCookieMatch[1]) {
|
|
try {
|
|
const decodedCookie = decodeURIComponent(insightsCookieMatch[1])
|
|
const insightsData = JSON.parse(decodedCookie)
|
|
distinctId = insightsData.distinct_id
|
|
} catch (e) {
|
|
console.error('Error parsing Insights cookie:', e)
|
|
}
|
|
}
|
|
}
|
|
await insights.captureException(err, distinctId || undefined)
|
|
}
|
|
}
|
|
`,
|
|
},
|
|
]}
|
|
/>
|
|
<Markdown>
|
|
{dedent`
|
|
You can find a full example of both this and client-side error tracking in our [Next.js error monitoring tutorial](https://hanzo.ai/tutorials/nextjs-error-monitoring).
|
|
`}
|
|
</Markdown>
|
|
</>
|
|
),
|
|
}
|
|
|
|
return [
|
|
...clientSteps,
|
|
captureClientExceptionsStep,
|
|
verifyClientStep,
|
|
installServerStep,
|
|
verifyServerStep,
|
|
captureServerExceptionsStep,
|
|
]
|
|
}
|
|
|
|
export const NextJSInstallation = createInstallation(getNextJSSteps)
|