Skip to content

Commit 4d77cfa

Browse files
rafaeelaudibertclaudesmallbrownbike
authored
docs: Add VS Code extension documentation (#16229)
* feat: Add VSCode extension documentation We're gonna be marketing this real soon, so let's add some docs here! This covers most of the features we have, we can easily extend documentation in the future if needed. Backlinking to the extension hasn't been done yet, I'd appreciate help from the editorial team here somehow. * fix: Address PR review feedback and add backlinks to VS Code extension docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: Restore internal backlinks from 253c736 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * import tab --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Eli Kinsey <eli@ekinsey.dev>
1 parent 1bb3ece commit 4d77cfa

16 files changed

Lines changed: 611 additions & 19 deletions

File tree

‎contents/blog/best-feature-flag-software-for-developers.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ DevCycle is a feature flag platform that prioritizes speed, simplicity, and tigh
210210

211211
DevCycle supports boolean and multivariate flags, percentage rollouts, user targeting, and environment management. It integrates with GitHub and Jira for flag lifecycle management, and includes built-in stale flag detection to help teams clean up technical debt.
212212

213-
What sets DevCycle apart is its obsession with developer workflow. It supports CLI and IDE-first ways to work with flags, plus integrations with tools like GitHub and Jira so flags show up naturally in code review and planning. And their edge and local-bucketing style options help keep evaluation fast without you managing a full flag platform yourself.
213+
What sets DevCycle apart is its obsession with developer workflow. It supports CLI and [IDE-first ways to work with flags](/docs/vscode-extension/flag-management), plus integrations with tools like GitHub and Jira so flags show up naturally in code review and planning. And their edge and local-bucketing style options help keep evaluation fast without you managing a full flag platform yourself.
214214

215215
DevCycle offers a free tier for up to 1,000 MAUs, with paid plans based on MAU volume.
216216

‎contents/docs/feature-flags/cutting-costs.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ The number of `/flags` requests and the number of `$feature_flag_called` events
4242

4343
Active feature flags you're not using in your code are still evaluated (and charged) every time the `/flags` endpoint is called. This includes when surveys are loaded, as survey targeting evaluates all active flags to determine eligibility.
4444

45-
To stop charges for unused flags, you must **disable, delete, or archive** them in the PostHog UI – simply removing them from your code is not enough.
45+
To stop charges for unused flags, you must **disable, delete, or archive** them in the PostHog UI – [simply removing them from your code](/docs/vscode-extension/stale-flag-cleanup) is not enough.
4646

4747
</CalloutBox>
4848

‎contents/docs/feature-flags/manage-flags-ai.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ title: Manage Feature Flags with PostHog AI
66

77
## How it works
88

9-
When you ask PostHog AI to create a flag, it creates it with your specified key and rollout percentage, configures targeting rules based on user properties, cohorts, or groups, and sets up variants and payloads for multivariate flags. It can also search your existing flags, identify stale flags not modified recently, and help you plan flag cleanup.
9+
When you ask PostHog AI to create a flag, it creates it with your specified key and rollout percentage, configures targeting rules based on user properties, cohorts, or groups, and sets up variants and payloads for multivariate flags. It can also search your existing flags, identify stale flags not modified recently, and help you plan [flag cleanup](/docs/vscode-extension/stale-flag-cleanup).
1010

1111
## Manage existing flags
1212

‎contents/docs/getting-started/next-steps.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ Read more about:
8989
- [Installing feature flags](/docs/feature-flags/installation) and [creating your first flag](/docs/feature-flags/creating-feature-flags)
9090
- [How we test in production](/product-engineers/testing-in-production) at PostHog using feature flags
9191
- [Best practices for using feature flags](/docs/feature-flags/best-practices) in your product
92+
- [VS Code extension](/docs/vscode-extension) — manage flags, see analytics, and clean up stale flags without leaving your editor
9293

9394
## 8. Try PostHog AI
9495

‎contents/docs/libraries/js/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ import IdentifyFrontendCallout from '../../_snippets/identify-frontend-callout.m
3131

3232
<IdentifyFrontendCallout />
3333

34-
Once you've installed PostHog, see our [features doc](/docs/libraries/js/features) for more information about what you can do with it.
34+
Once you've installed PostHog, see our [features doc](/docs/libraries/js/features) for more information about what you can do with it. You can also install the [PostHog VS Code extension](/docs/vscode-extension) to see live analytics, flag status, and session replay links inline in your code.
3535

3636
### Track across marketing website &amp; app
3737

‎contents/docs/model-context-protocol/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,5 +34,6 @@ We're working on adding more supported tools to the wizard. If you're using anot
3434
- [Replit integration](/docs/integrations/replit): Set up PostHog with Replit Agent
3535
- [v0 integration](/docs/integrations/v0): Set up PostHog with v0 and the Vercel Flags SDK
3636
- [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp): Check out GitHub repository for the MCP server
37+
- [PostHog VS Code extension](/docs/vscode-extension): Inline analytics, flag management, and session replay links in your editor
3738
- [Model Context Protocol](https://modelcontextprotocol.io/introduction): Learn more about the Model Context Protocol specification
3839
- [MCP: machine/copy paste](/blog/machine-copy-paste-mcp-intro): What exactly is MCP again?

‎contents/docs/model-context-protocol/vscode.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import SharedContent from "./_snippets/shared.mdx"
88

99
The PostHog [MCP server](https://modelcontextprotocol.io/introduction) enables VS Code to directly interact with your PostHog data – managing feature flags, querying analytics, investigating errors, and more.
1010

11+
> **Note:** This is different from the [PostHog VS Code extension](/docs/vscode-extension), which provides inline analytics, flag management, and session replay links directly in your editor. They complement each other.
12+
1113
## Server URL
1214

1315
| Region | URL |

‎contents/docs/vscode-extension/_snippets/configuration-reference.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Configuration reference
2+
3+
| Setting | Description | Default |
4+
|---|---|---|
5+
| `posthog.additionalClientNames` | Additional variable names the extension should recognize as instances of PostHog clients (e.g., `["analytics", "ph"]`) | `[]` |
6+
| `posthog.additionalFlagFunctions` | Additional bare function names that accept a flag key as the first argument (e.g., `["useMyFlag"]`) | `[]` |
7+
| `posthog.detectNestedClients` | Detect PostHog clients accessed via nested member expressions like `window.posthog?.capture()` | `true` |
8+
| `posthog.showInlineDecorations` | Show inline annotations (sparklines, flag status) in the editor | `true` |
9+
| `posthog.inlineHintsMode` | When to show inline hints: `always` or `currentLine` | `always` |
10+
| `posthog.staleFlagAgeDays` | Minimum number of days before a fully rolled out flag is considered stale | `30` |
11+
| `posthog.staleFlagExcludePatterns` | Glob patterns for files and directories to exclude from stale flag scanning | `[]` |
12+
| `posthog.useWorkspaceConfig` | Load configuration from a `.posthog.json` file in the workspace root | `true` |
13+
| `posthog.multiProjectNotifications` | Show notifications when switching between projects in a multi-project workspace | `true` |

‎contents/docs/vscode-extension/flag-management.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Flag management in the VS Code extension
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
The VS Code extension lets you create, toggle, edit, and manage [feature flags](/docs/feature-flags) without leaving your editor.
8+
9+
## Toggling flags
10+
11+
You can toggle a feature flag on or off from multiple places:
12+
13+
- **CodeLens** — Click the toggle action above a flag call in your code
14+
- **Right-click context menu** — Right-click on a flag key string and select the toggle option
15+
- **Sidebar Flags tab** — Click the toggle next to any flag in the list
16+
17+
A confirmation dialog appears before the change is applied to prevent accidental toggles. The change takes effect in PostHog immediately.
18+
19+
<ProductScreenshot
20+
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"
21+
alt="PostHog VS Code extension showing feature flag state"
22+
classes="rounded"
23+
/>
24+
25+
## Editing rollout and variants
26+
27+
From the flag detail panel (accessible via **PostHog: Show Flag Detail** or clicking a flag in the sidebar), you can edit:
28+
29+
- **Rollout percentage** — Adjust the percentage of users who see the flag
30+
- **Variant configuration** — Modify variant names, weights, and distribution
31+
- **Payloads** — Update the JSON payload associated with each variant
32+
33+
Changes are saved directly to PostHog.
34+
35+
## Creating flags from unrecognized keys
36+
37+
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:
38+
39+
1. Click **Create Feature Flag** in the quick-fix menu
40+
2. The extension creates the flag in PostHog using the key from your code
41+
3. The warning disappears after the next sync
42+
43+
This lets you write code with new flags first and create them in PostHog without switching context.
44+
45+
<ProductScreenshot
46+
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"
47+
alt="PostHog VS Code extension quick-fix to create a feature flag from an unrecognized key"
48+
classes="rounded"
49+
/>
50+
51+
## Generating TypeScript types
52+
53+
The extension can generate TypeScript types from your feature flag payload configurations, giving you type safety when working with flag values.
54+
55+
### All flags at once
56+
57+
Run **PostHog: Generate Flag Types** from the command palette to generate types for all flags in your project that have payload schemas defined.
58+
59+
### Individual flags
60+
61+
Right-click on a flag key in your code and select **PostHog: Generate Type** to generate a type for just that flag's payload.
62+
63+
The generated types reflect the structure of your flag payloads as configured in PostHog.
64+
65+
## Wrapping code in flag checks
66+
67+
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.
68+
69+
## Other flag actions
70+
71+
| Action | How to access | Command |
72+
|---|---|---|
73+
| **Copy flag key** | Right-click context menu or CodeLens | `PostHog: Copy Flag Key` |
74+
| **Open in PostHog** | CodeLens or sidebar — opens the flag in your browser | `PostHog: Open in PostHog` |
75+
| **Find all references** | Searches your workspace for every usage of a flag key | `PostHog: Find Flag References` |
76+
| **View flag detail** | Click a flag in the sidebar | `PostHog: Show Flag Detail` |

‎contents/docs/vscode-extension/index.mdx‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: VS Code extension
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
import Tab from "components/Tab"
8+
import ConfigurationReference from "./_snippets/configuration-reference.mdx"
9+
10+
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`).
11+
12+
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.
13+
14+
> **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.
15+
16+
## Installation
17+
18+
Install directly from your editor:
19+
20+
<Tab.Group tabs={['VS Code', 'Cursor']}>
21+
<Tab.List>
22+
<Tab>VS Code</Tab>
23+
<Tab>Cursor</Tab>
24+
</Tab.List>
25+
<Tab.Panels>
26+
<Tab.Panel>
27+
28+
[Install in VS Code](vscode:extension/PostHog.posthog-vscode)
29+
30+
</Tab.Panel>
31+
<Tab.Panel>
32+
33+
[Install in Cursor](cursor:extension/PostHog.posthog-vscode)
34+
35+
</Tab.Panel>
36+
</Tab.Panels>
37+
</Tab.Group>
38+
39+
Or install manually:
40+
41+
1. Open the Extensions panel (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux)
42+
2. Search for **"PostHog"**
43+
3. Click **Install**
44+
45+
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).
46+
47+
<ProductScreenshot
48+
imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_04_07_T17_17_54_254_Z_0a1811dac8.png"
49+
alt="PostHog VS Code extension in the marketplace"
50+
classes="rounded"
51+
/>
52+
53+
> **Requirements:**
54+
> - VS Code 1.109.0 or later
55+
> - A PostHog account
56+
57+
## Authentication
58+
59+
Once installed, authenticate the extension with your PostHog account:
60+
61+
1. Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
62+
2. Run `PostHog: Sign In`
63+
3. Click the sign-in button — this opens PostHog in your browser where you authenticate via OAuth
64+
4. Once authenticated, run **PostHog: Select Project** to choose which project to connect to
65+
66+
After authenticating, the status bar at the bottom of VS Code shows your active project and last sync time.
67+
68+
<ProductScreenshot
69+
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"
70+
alt="PostHog VS Code extension sign-in flow"
71+
classes="rounded max-w-md"
72+
/>
73+
74+
## Quick start
75+
76+
Once connected, the extension immediately starts analyzing your code:
77+
78+
- **SDK initialization diagnostics** help you verify that your PostHog `init()` calls are configured correctly, surfacing warnings if something looks off
79+
- **Inline decorations** appear next to `posthog.capture()` calls showing 7-day event volume sparklines
80+
- **Feature flag status** indicators show next to `posthog.isFeatureEnabled()` and `posthog.getFeatureFlag()` calls
81+
- **CodeLens** actions appear above flag and capture calls with contextual links
82+
- The **sidebar** populates with your feature flags, experiments, and saved insights
83+
84+
<ProductScreenshot
85+
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"
86+
alt="PostHog VS Code extension quick start"
87+
classes="rounded"
88+
/>
89+
90+
For details on each feature, see:
91+
92+
| Feature | Description |
93+
|---|---|
94+
| [Inline code intelligence](/docs/vscode-extension/inline-code-intelligence) | Sparklines, flag status, autocomplete, and more |
95+
| [Sidebar dashboard](/docs/vscode-extension/sidebar-dashboard) | Flags, experiments, analytics, and X-ray tabs |
96+
| [Flag management](/docs/vscode-extension/flag-management) | Toggle, edit, create, and generate types for flags |
97+
| [Stale flag cleanup](/docs/vscode-extension/stale-flag-cleanup) | Find and remove outdated flag checks |
98+
| [Session replay](/docs/vscode-extension/session-replay) | See session and user counts, jump to replays |
99+
100+
## Team configuration
101+
102+
Share extension settings across your team by committing a `.posthog.json` file to your repository root:
103+
104+
```json
105+
{
106+
"projectId": 12345,
107+
"additionalClientNames": ["analytics"],
108+
"additionalFlagFunctions": ["useMyFlag"]
109+
}
110+
```
111+
112+
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.
113+
114+
### Multi-project workspaces
115+
116+
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.
117+
118+
Set `posthog.multiProjectNotifications` to `true` (default) to get notified when the active project changes.
119+
120+
### Automatic sync
121+
122+
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.
123+
124+
<ConfigurationReference />
125+
126+
## Commands reference
127+
128+
Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type "PostHog" to see all available commands.
129+
130+
### Authentication and setup
131+
132+
| Command | Description |
133+
|---|---|
134+
| `PostHog: Sign In` | Authenticate with your PostHog personal API key |
135+
| `PostHog: Sign Out` | Disconnect from PostHog |
136+
| `PostHog: Select Project` | Choose which PostHog project to use |
137+
| `PostHog: Run Setup Wizard` | Guided setup for first-time configuration |
138+
139+
### Feature flags
140+
141+
| Command | Description |
142+
|---|---|
143+
| `PostHog: Refresh Feature Flags` | Fetch the latest flags from PostHog |
144+
| `PostHog: Create Feature Flag` | Create a new flag in PostHog |
145+
| `PostHog: Copy Flag Key` | Copy a flag key to the clipboard |
146+
| `PostHog: Show Flag Detail` | Open the detail panel for a flag |
147+
| `PostHog: Open in PostHog` | Open the flag or experiment in your browser |
148+
| `PostHog: Find Flag References` | Search the workspace for all usages of a flag key |
149+
| `PostHog: Generate Flag Types` | Generate TypeScript types for all flag payloads |
150+
| `PostHog: Generate Type` | Generate a TypeScript type for a single flag (context menu) |
151+
152+
### Experiments
153+
154+
| Command | Description |
155+
|---|---|
156+
| `PostHog: Show Experiment Detail` | Open the detail panel for an experiment |
157+
158+
### Session replay
159+
160+
| Command | Description |
161+
|---|---|
162+
| `PostHog: Watch Sessions` | View sessions for an event in your browser |
163+
164+
### Stale flags
165+
166+
| Command | Description |
167+
|---|---|
168+
| `PostHog: Scan for Stale Flags` | Scan the workspace for stale feature flag references |
169+
| `PostHog: Clean Up Stale Flag` | Remove a stale flag check from the code |
170+
171+
## Further reading
172+
173+
- [PostHog VS Code extension on GitHub](https://github.com/PostHog/posthog-vscode)
174+
- [PostHog MCP server for VS Code](/docs/model-context-protocol/vscode) — AI agent integration
175+
- [Feature flags documentation](/docs/feature-flags)

0 commit comments

Comments
 (0)