-
Notifications
You must be signed in to change notification settings - Fork 777
docs: Add VS Code extension documentation #16229
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
rafaeelaudibert
wants to merge
3
commits into
master
Choose a base branch
from
rafa/feat-add-vscode-extension-documentation
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
13 changes: 13 additions & 0 deletions
13
contents/docs/vscode-extension/_snippets/configuration-reference.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| ## Configuration reference | ||
|
|
||
| | Setting | Description | Default | | ||
| |---|---|---| | ||
| | `posthog.additionalClientNames` | Additional variable names the extension should recognize as instances of PostHog clients (e.g., `["analytics", "ph"]`) | `[]` | | ||
| | `posthog.additionalFlagFunctions` | Additional bare function names that accept a flag key as the first argument (e.g., `["useMyFlag"]`) | `[]` | | ||
| | `posthog.detectNestedClients` | Detect PostHog clients accessed via nested member expressions like `window.posthog?.capture()` | `true` | | ||
| | `posthog.showInlineDecorations` | Show inline annotations (sparklines, flag status) in the editor | `true` | | ||
| | `posthog.inlineHintsMode` | When to show inline hints: `always` or `currentLine` | `always` | | ||
| | `posthog.staleFlagAgeDays` | Minimum number of days before a fully rolled out flag is considered stale | `30` | | ||
| | `posthog.staleFlagExcludePatterns` | Glob patterns for files and directories to exclude from stale flag scanning | `[]` | | ||
| | `posthog.useWorkspaceConfig` | Load configuration from a `.posthog.json` file in the workspace root | `true` | | ||
| | `posthog.multiProjectNotifications` | Show notifications when switching between projects in a multi-project workspace | `true` | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| --- | ||
| title: Flag management in the VS Code extension | ||
| sidebar: Docs | ||
| showTitle: true | ||
| --- | ||
|
|
||
| The VS Code extension lets you create, toggle, edit, and manage [feature flags](/docs/feature-flags) without leaving your editor. | ||
|
|
||
| ## Toggling flags | ||
|
|
||
| You can toggle a feature flag on or off from multiple places: | ||
|
|
||
| - **CodeLens** — Click the toggle action above a flag call in your code | ||
| - **Right-click context menu** — Right-click on a flag key string and select the toggle option | ||
| - **Sidebar Flags tab** — Click the toggle next to any flag in the list | ||
|
|
||
| A confirmation dialog appears before the change is applied to prevent accidental toggles. The change takes effect in PostHog immediately. | ||
|
|
||
| <ProductScreenshot | ||
| imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1000,c_limit,q_auto,f_auto/pasted_image_2026_04_08_T00_01_21_431_Z_8c2c911a53.png" | ||
| alt="PostHog VS Code extension showing feature flag state" | ||
| classes="rounded" | ||
| /> | ||
|
|
||
| ## Editing rollout and variants | ||
|
|
||
| From the flag detail panel (accessible via **PostHog: Show Flag Detail** or clicking a flag in the sidebar), you can edit: | ||
|
|
||
| - **Rollout percentage** — Adjust the percentage of users who see the flag | ||
| - **Variant configuration** — Modify variant names, weights, and distribution | ||
| - **Payloads** — Update the JSON payload associated with each variant | ||
|
|
||
| Changes are saved directly to PostHog. | ||
|
|
||
| ## Creating flags from unrecognized keys | ||
|
|
||
| When the extension detects a flag key in your code that doesn't exist in your PostHog project, it shows a **yellow underline warning**. Hover over the warning to see a quick-fix action: | ||
|
|
||
| 1. Click **Create Feature Flag** in the quick-fix menu | ||
| 2. The extension creates the flag in PostHog using the key from your code | ||
| 3. The warning disappears after the next sync | ||
|
|
||
| This lets you write code with new flags first and create them in PostHog without switching context. | ||
|
|
||
| <ProductScreenshot | ||
| imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/pasted_image_2026_04_08_T00_02_16_887_Z_9563f497ce.png" | ||
| alt="PostHog VS Code extension quick-fix to create a feature flag from an unrecognized key" | ||
| classes="rounded" | ||
| /> | ||
|
|
||
| ## Generating TypeScript types | ||
|
|
||
| The extension can generate TypeScript types from your feature flag payload configurations, giving you type safety when working with flag values. | ||
|
|
||
| ### All flags at once | ||
|
|
||
| Run **PostHog: Generate Flag Types** from the command palette to generate types for all flags in your project that have payload schemas defined. | ||
|
|
||
| ### Individual flags | ||
|
|
||
| Right-click on a flag key in your code and select **PostHog: Generate Type** to generate a type for just that flag's payload. | ||
|
|
||
| The generated types reflect the structure of your flag payloads as configured in PostHog. | ||
|
|
||
| ## Wrapping code in flag checks | ||
|
|
||
| Select a block of code, then use the context menu or command palette to **wrap it in a feature flag check**. The extension inserts the appropriate `isFeatureEnabled()` or `getFeatureFlag()` call around your selection, prompting you to choose which flag to use. | ||
|
|
||
| ## Other flag actions | ||
|
|
||
| | Action | How to access | Command | | ||
| |---|---|---| | ||
| | **Copy flag key** | Right-click context menu or CodeLens | `PostHog: Copy Flag Key` | | ||
| | **Open in PostHog** | CodeLens or sidebar — opens the flag in your browser | `PostHog: Open in PostHog` | | ||
| | **Find all references** | Searches your workspace for every usage of a flag key | `PostHog: Find Flag References` | | ||
| | **View flag detail** | Click a flag in the sidebar | `PostHog: Show Flag Detail` | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,174 @@ | ||
| --- | ||
| title: VS Code extension | ||
| sidebar: Docs | ||
| showTitle: true | ||
| --- | ||
|
|
||
| import ConfigurationReference from "./_snippets/configuration-reference.mdx" | ||
|
|
||
| The [PostHog VS Code extension](https://marketplace.visualstudio.com/items?itemName=PostHog.posthog-vscode) brings feature flags, experiments, event analytics, and session replay data directly into your editor. It works with JavaScript, TypeScript, Go and Ruby files (`.js`, `.jsx`, `.ts`, `.tsx`, `.go`, `.rb`). | ||
|
|
||
| With it, you can see live analytics data inline in your code, [manage feature flags](/docs/vscode-extension/flag-management) without leaving your editor, [clean up stale flags](/docs/vscode-extension/stale-flag-cleanup) with AST-based refactoring, and [jump to session replays](/docs/vscode-extension/session-replay) for events in your codebase. | ||
|
|
||
| > **Note:** This extension is different from the [PostHog MCP server for VS Code](/docs/model-context-protocol/vscode), which enables AI agents and Copilot to interact with PostHog. The VS Code extension provides direct, visual tooling for developers in the editor. They complement each other. | ||
|
|
||
| ## Installation | ||
|
|
||
| Install directly from your editor: | ||
|
|
||
| <Tab.Group tabs={['VS Code', 'Cursor']}> | ||
| <Tab.List> | ||
| <Tab>VS Code</Tab> | ||
| <Tab>Cursor</Tab> | ||
| </Tab.List> | ||
| <Tab.Panels> | ||
| <Tab.Panel> | ||
|
|
||
| [Install in VS Code](vscode:extension/PostHog.posthog-vscode) | ||
|
|
||
| </Tab.Panel> | ||
| <Tab.Panel> | ||
|
|
||
| [Install in Cursor](cursor:extension/PostHog.posthog-vscode) | ||
|
|
||
| </Tab.Panel> | ||
| </Tab.Panels> | ||
| </Tab.Group> | ||
|
|
||
| Or install manually: | ||
|
|
||
| 1. Open the Extensions panel (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux) | ||
| 2. Search for **"PostHog"** | ||
| 3. Click **Install** | ||
|
|
||
| The extension is also available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=PostHog.posthog-vscode) and the [Open VSX Registry](https://open-vsx.org/extension/PostHog/posthog-vscode). | ||
|
|
||
| <ProductScreenshot | ||
| imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_04_07_T17_17_54_254_Z_0a1811dac8.png" | ||
| alt="PostHog VS Code extension in the marketplace" | ||
| classes="rounded" | ||
| /> | ||
|
|
||
| > **Requirements:** | ||
| > - VS Code 1.109.0 or later | ||
| > - A PostHog account | ||
|
|
||
| ## Authentication | ||
|
|
||
| Once installed, authenticate the extension with your PostHog account: | ||
|
|
||
| 1. Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) | ||
| 2. Run `PostHog: Sign In` | ||
| 3. Click the sign-in button — this opens PostHog in your browser where you authenticate via OAuth | ||
| 4. Once authenticated, run **PostHog: Select Project** to choose which project to connect to | ||
|
|
||
| After authenticating, the status bar at the bottom of VS Code shows your active project and last sync time. | ||
|
|
||
| <ProductScreenshot | ||
| imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_500,c_limit,q_auto,f_auto/pasted_image_2026_04_07_T17_30_26_682_Z_279700c593.png" | ||
| alt="PostHog VS Code extension sign-in flow" | ||
| classes="rounded max-w-md" | ||
| /> | ||
|
|
||
| ## Quick start | ||
|
|
||
| Once connected, the extension immediately starts analyzing your code: | ||
|
|
||
| - **SDK initialization diagnostics** help you verify that your PostHog `init()` calls are configured correctly, surfacing warnings if something looks off | ||
| - **Inline decorations** appear next to `posthog.capture()` calls showing 7-day event volume sparklines | ||
| - **Feature flag status** indicators show next to `posthog.isFeatureEnabled()` and `posthog.getFeatureFlag()` calls | ||
| - **CodeLens** actions appear above flag and capture calls with contextual links | ||
| - The **sidebar** populates with your feature flags, experiments, and saved insights | ||
|
|
||
| <ProductScreenshot | ||
| imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1000,c_limit,q_auto,f_auto/pasted_image_2026_04_07_T17_48_06_446_Z_3ff1a0d2aa.png" | ||
| alt="PostHog VS Code extension quick start" | ||
| classes="rounded" | ||
| /> | ||
|
|
||
| For details on each feature, see: | ||
|
|
||
| | Feature | Description | | ||
| |---|---| | ||
| | [Inline code intelligence](/docs/vscode-extension/inline-code-intelligence) | Sparklines, flag status, autocomplete, and more | | ||
| | [Sidebar dashboard](/docs/vscode-extension/sidebar-dashboard) | Flags, experiments, analytics, and X-ray tabs | | ||
| | [Flag management](/docs/vscode-extension/flag-management) | Toggle, edit, create, and generate types for flags | | ||
| | [Stale flag cleanup](/docs/vscode-extension/stale-flag-cleanup) | Find and remove outdated flag checks | | ||
| | [Session replay](/docs/vscode-extension/session-replay) | See session and user counts, jump to replays | | ||
|
|
||
| ## Team configuration | ||
|
|
||
| Share extension settings across your team by committing a `.posthog.json` file to your repository root: | ||
|
|
||
| ```json | ||
| { | ||
| "projectId": 12345, | ||
| "additionalClientNames": ["analytics"], | ||
| "additionalFlagFunctions": ["useMyFlag"] | ||
| } | ||
| ``` | ||
|
|
||
| This ensures everyone on the team connects to the correct project and the extension recognizes your custom PostHog client variable names and flag wrapper functions. | ||
|
|
||
| ### Multi-project workspaces | ||
|
|
||
| If your VS Code workspace contains multiple folders connected to different PostHog projects, the extension detects this automatically. Each folder can have its own `.posthog.json` with a different `projectId`. The extension switches context as you navigate between files in different folders. | ||
|
|
||
| Set `posthog.multiProjectNotifications` to `true` (default) to get notified when the active project changes. | ||
|
|
||
| ### Automatic sync | ||
|
|
||
| The extension periodically refreshes its cache of feature flags, experiments, and event data from PostHog. The status bar shows when the last sync occurred. You can also manually refresh with the **PostHog: Refresh Feature Flags** command. | ||
|
|
||
| <ConfigurationReference /> | ||
|
|
||
| ## Commands reference | ||
|
|
||
| Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type "PostHog" to see all available commands. | ||
|
|
||
| ### Authentication and setup | ||
|
|
||
| | Command | Description | | ||
| |---|---| | ||
| | `PostHog: Sign In` | Authenticate with your PostHog personal API key | | ||
| | `PostHog: Sign Out` | Disconnect from PostHog | | ||
| | `PostHog: Select Project` | Choose which PostHog project to use | | ||
| | `PostHog: Run Setup Wizard` | Guided setup for first-time configuration | | ||
|
|
||
| ### Feature flags | ||
|
|
||
| | Command | Description | | ||
| |---|---| | ||
| | `PostHog: Refresh Feature Flags` | Fetch the latest flags from PostHog | | ||
| | `PostHog: Create Feature Flag` | Create a new flag in PostHog | | ||
| | `PostHog: Copy Flag Key` | Copy a flag key to the clipboard | | ||
| | `PostHog: Show Flag Detail` | Open the detail panel for a flag | | ||
| | `PostHog: Open in PostHog` | Open the flag or experiment in your browser | | ||
| | `PostHog: Find Flag References` | Search the workspace for all usages of a flag key | | ||
| | `PostHog: Generate Flag Types` | Generate TypeScript types for all flag payloads | | ||
| | `PostHog: Generate Type` | Generate a TypeScript type for a single flag (context menu) | | ||
|
|
||
| ### Experiments | ||
|
|
||
| | Command | Description | | ||
| |---|---| | ||
| | `PostHog: Show Experiment Detail` | Open the detail panel for an experiment | | ||
|
|
||
| ### Session replay | ||
|
|
||
| | Command | Description | | ||
| |---|---| | ||
| | `PostHog: Watch Sessions` | View sessions for an event in your browser | | ||
|
|
||
| ### Stale flags | ||
|
|
||
| | Command | Description | | ||
| |---|---| | ||
| | `PostHog: Scan for Stale Flags` | Scan the workspace for stale feature flag references | | ||
| | `PostHog: Clean Up Stale Flag` | Remove a stale flag check from the code | | ||
|
|
||
| ## Further reading | ||
|
|
||
| - [PostHog VS Code extension on GitHub](https://github.com/PostHog/posthog-vscode) | ||
| - [PostHog MCP server for VS Code](/docs/model-context-protocol/vscode) — AI agent integration | ||
| - [Feature flags documentation](/docs/feature-flags) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay for bonus credits, can we frame this screenshot or take a wider screenshot with the background? The dimensions of this are such that it doesn't fit on my screen :P
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought
ProductScreenshotwould frame it. I'll see what I can do to get this to a good state