:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { useValues } from 'kea'
import React, { Children, ReactNode, createContext, isValidElement, useContext, useMemo } from 'react'
import { StepProps, StepsProps } from '@posthog/shared-onboarding/steps'
import { StepDefinition, StepModifier } from '@posthog/shared-onboarding/steps'
import { PROSE_LANGUAGE } from '@posthog/shared-onboarding/steps'
import { CodeSnippet, getLanguage } from 'lib/components/CodeSnippet'
import { CopyToClipboardInline } from 'lib/components/CopyToClipboard'
import { LemonBanner } from 'lib/lemon-ui/LemonBanner'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { LemonMarkdown } from 'lib/lemon-ui/LemonMarkdown'
import { LemonTabs } from 'lib/lemon-ui/LemonTabs'
import { LemonTag } from 'lib/lemon-ui/LemonTag'
import { apiHostOrigin } from 'lib/utils/apiHost'
import { domainFor, proxyLogic } from 'scenes/settings/environment/proxyLogic'
import { teamLogic } from 'scenes/teamLogic'
export interface OnboardingComponentsContext {
Steps: React.ComponentType<StepsProps>
Step: React.ComponentType<StepProps>
CodeBlock: React.ComponentType<{
blocks?: Array<{ language: string; code: string; file?: string }>
language?: string
code?: string
file?: string
}>
CalloutBox: React.ComponentType<{
type: 'action' | 'fyi' | 'caution' | 'info'
icon?: string
title?: string
children: ReactNode
}>
ProductScreenshot: React.ComponentType<{
imageLight: string
imageDark: string
alt: string
classes?: string
className?: string
padding?: boolean
}>
OSButton: React.ComponentType<any>
Markdown: React.ComponentType<{ children: string | ReactNode }>
Blockquote: React.ComponentType<{ children: ReactNode }>
dedent: (strings: TemplateStringsArray | string, ...values: any[]) => string
Tab: {
Group: React.ComponentType<{ tabs: string[]; children: ReactNode }>
List: React.ComponentType<{ children: ReactNode }>
Panels: React.ComponentType<{ children: ReactNode }>
Panel: React.ComponentType<{ children: ReactNode }>
} & React.ComponentType<{ children: ReactNode }>
snippets?: Record<string, React.ComponentType<any>>
selectedFile?: string | null
setSelectedFile?: (file: string) => void
apiHost?: string
}
const OnboardingContext = createContext<OnboardingComponentsContext | null>(null)
const SelectedFileContext = createContext<{
selectedFile: string | null
setSelectedFile: (file: string) => void
} | null>(null)
/**
* Keeps the code block file choice (for example Python or Node) outside the content wrapper, so a
* surface that swaps the whole instruction tree keeps the reader's choice instead of resetting it.
*/
export function OnboardingSelectedFileProvider({ children }: { children: ReactNode }): JSX.Element {
const [selectedFile, setSelectedFile] = React.useState<string | null>(null)
const value = useMemo(() => ({ selectedFile, setSelectedFile }), [selectedFile])
return <SelectedFileContext.Provider value={value}>{children}</SelectedFileContext.Provider>
}
function Steps({ children }: StepsProps): JSX.Element {
let stepNumber = 0
const processedChildren = Children.map(children, (child) => {
if (!isValidElement(child)) {
return child
}
// Only number Step components - check if it's actually a Step component
const isStep = child.type === Step && 'title' in child.props && typeof child.props.title === 'string'
if (isStep && !child.props.docsOnly) {
stepNumber += 1
return React.cloneElement(child, { stepNumber } as any)
}
return child
})
return <div className="space-y-6">{processedChildren}</div>
}
function Step({
title,
subtitle,
badge,
docsOnly,
stepNumber,
children,
}: StepProps & { stepNumber?: number }): JSX.Element | null {
if (docsOnly) {
return null
}
const numberedTitle = stepNumber ? `${stepNumber}. ${title}` : title
return (
<div className="space-y-4">
<div className="flex items-center gap-2">
<h3 className="m-0">{numberedTitle}</h3>
{badge && (
<LemonTag
type={badge === 'required' ? 'default' : badge === 'recommended' ? 'success' : 'option'}
className="text-xs"
>
{badge}
</LemonTag>
)}
</div>
{subtitle && <p className="text-muted text-sm m-0">{subtitle}</p>}
<div className="space-y-4">{children}</div>
</div>
)
}
interface CodeBlockItem {
language: string
code: string
file?: string
}
function CodeBlock({
blocks,
language,
code,
file,
}: {
blocks?: Array<{ language: string; code: string; file?: string }>
language?: string
code?: string
file?: string
}): JSX.Element {
const context = useContext(OnboardingContext)
const globalSelectedFile = context?.selectedFile
const globalSetSelectedFile = context?.setSelectedFile
const { currentTeam } = useValues(teamLogic)
const host = context?.apiHost ?? apiHostOrigin()
const replacePlaceholders = (codeString: string): string => {
return codeString
.replace(/<ph_project_token>/g, currentTeam?.api_token ?? '<ph_project_token>')
.replace(/<ph_client_api_host>/g, host)
.replace(/<team_id>/g, currentTeam?.id?.toString() ?? '<team_id>')
}
// If blocks array is provided, use it
const codeBlocks: CodeBlockItem[] = blocks
? blocks.map((block) => ({
language: block.language,
code: replacePlaceholders(block.code),
file: block.file,
}))
: // Otherwise, use single block props
language && code
? [
{
language,
code: replacePlaceholders(code),
file,
},
]
: []
// The API host is substituted into the snippet as inert highlighted text, so surface it as a
// standalone, copyable value — users otherwise try (and fail) to click or copy it in the snippet.
const rawCodeStrings = blocks ? blocks.map((block) => block.code) : code ? [code] : []
const hostUsed = rawCodeStrings.some((codeString) => codeString.includes('<ph_client_api_host>'))
const hostHint = hostUsed ? (
<div className="flex items-center gap-1 text-xs text-muted mt-1">
<span>API host:</span>
<CopyToClipboardInline explicitValue={host} description="API host" iconSize="xsmall" selectable>
{host}
</CopyToClipboardInline>
</div>
) : null
const uniqueFiles = codeBlocks
.map((block) => block.file || 'default')
.filter((file, index, self) => self.indexOf(file) === index)
// Use global selected file if available and it exists in this block's files
const selectedFile =
globalSelectedFile && uniqueFiles.includes(globalSelectedFile) ? globalSelectedFile : uniqueFiles[0] || null
const setSelectedFile = (file: string): void => {
if (globalSetSelectedFile) {
globalSetSelectedFile(file)
}
}
if (codeBlocks.length === 0) {
return <></>
}
if (codeBlocks.length === 1) {
const block = codeBlocks[0]
return (
<div className="my-4">
{block.language === PROSE_LANGUAGE ? (
<LemonMarkdown>{block.code}</LemonMarkdown>
) : (
<CodeSnippet language={getLanguage(block.language)}>{block.code}</CodeSnippet>
)}
{hostHint}
</div>
)
}
// Multiple code blocks - use tabs
const selectedBlock = codeBlocks.find((block) => (block.file || 'default') === selectedFile)
if (!selectedBlock) {
return <></>
}
return (
<div className="space-y-2">
{uniqueFiles.length > 1 && (
<LemonTabs
activeKey={selectedFile || uniqueFiles[0]}
onChange={(key) => setSelectedFile(key as string)}
tabs={uniqueFiles.map((file) => ({
key: file,
label: file,
}))}
/>
)}
{selectedBlock.language === PROSE_LANGUAGE ? (
<LemonMarkdown>{selectedBlock.code}</LemonMarkdown>
) : (
<CodeSnippet language={getLanguage(selectedBlock.language)}>{selectedBlock.code}</CodeSnippet>
)}
{hostHint}
</div>
)
}
function CalloutBox({
type,
title,
children,
}: {
type: 'action' | 'fyi' | 'caution' | 'info'
icon?: string
title?: string
children: ReactNode
}): JSX.Element {
const bannerType = type === 'caution' ? 'warning' : 'info'
return (
<LemonBanner type={bannerType} className="my-4 [&>*]:font-normal">
{title && <strong>{title}</strong>}
{children}
</LemonBanner>
)
}
function ProductScreenshot({
imageLight,
alt,
classes,
className,
padding = true,
}: {
imageLight: string
imageDark?: string
alt: string
classes?: string
className?: string
padding?: boolean
}): JSX.Element {
return (
<div className={className}>
<img src={imageLight} alt={alt} className={`${classes || ''} ${padding ? 'p-4' : ''}`} />
</div>
)
}
function OSButton(props: any): JSX.Element {
return <LemonButton {...props} />
}
function Markdown({ children }: { children: string | ReactNode }): JSX.Element {
const content = typeof children === 'string' ? children : String(children)
return <LemonMarkdown>{content}</LemonMarkdown>
}
function Blockquote({ children }: { children: ReactNode }): JSX.Element {
return (
<LemonBanner type="info" className="my-4 [&>*]:font-normal">
{children}
</LemonBanner>
)
}
const TabContext = createContext<{ activeTab: number; setActiveTab: (index: number) => void } | null>(null)
function TabGroup({ tabs, children }: { tabs: string[]; children: ReactNode }): JSX.Element {
const [activeTab, setActiveTab] = React.useState(0)
return (
<TabContext.Provider value={{ activeTab, setActiveTab }}>
<div>
<LemonTabs
activeKey={String(activeTab)}
onChange={(key) => setActiveTab(Number(key))}
tabs={tabs.map((tab, idx) => ({ key: String(idx), label: tab }))}
/>
{children}
</div>
</TabContext.Provider>
)
}
function TabList(): JSX.Element {
// Tab.List is not rendered, it's just for compatibility with Website tabs
return <></>
}
function TabItem(): JSX.Element {
// Individual Tab items are not rendered, it's just for compatibility with Website tabs
return <></>
}
function TabPanels({ children }: { children: ReactNode }): JSX.Element {
const context = useContext(TabContext)
if (!context) {
throw new Error('Tab.Panels must be used within Tab.Group')
}
const panels = Children.toArray(children)
return <div className="mt-4">{panels[context.activeTab]}</div>
}
function TabPanel({ children }: { children: ReactNode }): JSX.Element {
return <>{children}</>
}
const Tab = Object.assign(TabItem, {
Group: TabGroup,
List: TabList,
Panels: TabPanels,
Panel: TabPanel,
})
function MinimalSteps({ children }: StepsProps): JSX.Element {
return <div className="space-y-4">{children}</div>
}
function MinimalStep({ title, docsOnly, children }: StepProps): JSX.Element | null {
if (docsOnly) {
return null
}
return (
<div className="space-y-2">
{title && <h4 className="m-0">{title}</h4>}
<div className="space-y-4">{children}</div>
</div>
)
}
// This is a wrapper to share certain onboarding instructions with the main website repo.
export function OnboardingDocsContentWrapper({
children,
snippets,
createSnippets,
minimal,
useReverseProxy,
}: {
children: ReactNode
snippets?: Record<string, React.ComponentType<any>>
createSnippets?: (components: OnboardingComponentsContext) => Record<string, React.ComponentType<any>>
minimal?: boolean
/** When true, code snippets show the reverse proxy domain (if one exists) instead of the default API host. */
useReverseProxy?: boolean
}): JSX.Element {
const [localSelectedFile, setLocalSelectedFile] = React.useState<string | null>(null)
const { selectedFile, setSelectedFile } = useContext(SelectedFileContext) ?? {
selectedFile: localSelectedFile,
setSelectedFile: setLocalSelectedFile,
}
const { proxyRecords } = useValues(proxyLogic)
const apiHost = useMemo(() => {
if (useReverseProxy) {
return domainFor(proxyRecords.find((r) => r.status === 'valid'))
}
return apiHostOrigin()
}, [useReverseProxy, proxyRecords])
const baseComponents = useMemo<Omit<OnboardingComponentsContext, 'snippets'>>(
() => ({
Steps: minimal ? MinimalSteps : Steps,
Step: minimal ? MinimalStep : Step,
CodeBlock,
CalloutBox,
ProductScreenshot,
OSButton,
Markdown,
Blockquote,
dedent,
Tab,
selectedFile,
setSelectedFile,
apiHost,
}),
[selectedFile, minimal, apiHost]
)
const finalSnippets = useMemo(() => {
if (createSnippets) {
return createSnippets(baseComponents as OnboardingComponentsContext)
}
return snippets
}, [createSnippets, snippets, baseComponents])
const components = useMemo<OnboardingComponentsContext>(
() =>
({
...baseComponents,
snippets: finalSnippets,
}) as OnboardingComponentsContext,
[baseComponents, finalSnippets]
)
return (
<OnboardingContext.Provider value={components}>
<div className="w-full">{children}</div>
</OnboardingContext.Provider>
)
}
export function useMDXComponents(): OnboardingComponentsContext {
const context = useContext(OnboardingContext)
if (!context) {
throw new Error('useMDXComponents must be used within OnboardingDocsContentWrapper')
}
return context
}
/**
* Removes leading indentation from a template literal string.
* Useful for formatting code blocks and markdown content in JSX.
*
* @param strings - Template literal strings
* @param values - Interpolated values
* @returns Dedented string
*/
export function dedent(strings: TemplateStringsArray | string, ...values: any[]): string {
const str =
typeof strings === 'string'
? strings
: Array.isArray(strings)
? strings.reduce((acc, s, i) => acc + s + (values[i] || ''), '')
: String(strings)
const lines = str.split('\n')
const firstNonEmptyLine = lines.find((line) => line.trim())
if (!firstNonEmptyLine) {
return str.trim()
}
const indent = firstNonEmptyLine.match(/^(\s*)/)?.[1]?.length || 0
return lines
.map((line) => (line.length >= indent ? line.slice(indent) : line))
.join('\n')
.trim()
}
/**
* Creates an Installation component from a steps function.
*/
export function createInstallation(
getSteps: (ctx: OnboardingComponentsContext) => StepDefinition[]
): React.ComponentType<StepModifier> {
return function Installation({ modifySteps }: StepModifier = {}) {
const components = useMDXComponents()
const { Steps, Step } = components
let steps = getSteps(components)
if (modifySteps) {
steps = modifySteps(steps)
}
return (
<Steps>
{steps.map((step, index) => (
<Step key={index} title={step.title} badge={step.badge}>
{step.content}
</Step>
))}
</Steps>
)
}
}