Adds welcome page webview for first-time installs

sergeibbb · sergeibbb · commit 1eb1125e3f6c · 2025-12-02T18:20:36.000+01:00
(#4769, PLG-138)
diff --git a/contributions.json b/contributions.json
@@ -5657,6 +5657,11 @@
 			"label": "Show Visual File History View",
 			"commandPalette": "gitlens:enabled"
 		},
+		"gitlens.showWelcomePage": {
+			"label": "Show Welcome",
+			"icon": "$(heart)",
+			"commandPalette": "gitlens:enabled"
+		},
 		"gitlens.showWorkspacesView": {
 			"label": "Show Cloud Workspaces View",
 			"commandPalette": "gitlens:enabled && !gitlens:hasVirtualFolders"
diff --git a/docs/telemetry-events.md b/docs/telemetry-events.md
@@ -3537,3 +3537,42 @@ or
 }
 ```
 
+### welcome/closed
+
+```typescript
+{
+  [`context.${string}`]: string | number | boolean,
+  'context.webview.host': 'view' | 'editor',
+  'context.webview.id': string,
+  'context.webview.instanceId': string,
+  'context.webview.type': string
+}
+```
+
+### welcome/showAborted
+
+```typescript
+{
+  'context.webview.host': 'view' | 'editor',
+  'context.webview.id': string,
+  'context.webview.instanceId': string,
+  'context.webview.type': string,
+  'duration': number,
+  'loading': boolean
+}
+```
+
+### welcome/shown
+
+```typescript
+{
+  [`context.${string}`]: string | number | boolean,
+  'context.webview.host': 'view' | 'editor',
+  'context.webview.id': string,
+  'context.webview.instanceId': string,
+  'context.webview.type': string,
+  'duration': number,
+  'loading': boolean
+}
+```
+
diff --git a/package.json b/package.json
@@ -8344,6 +8344,12 @@
 				"title": "Show Visual File History View",
 				"category": "GitLens"
 			},
+			{
+				"command": "gitlens.showWelcomePage",
+				"title": "Show Welcome",
+				"category": "GitLens",
+				"icon": "$(heart)"
+			},
 			{
 				"command": "gitlens.showWorkspacesView",
 				"title": "Show Cloud Workspaces View",
@@ -13156,6 +13162,10 @@
 					"command": "gitlens.showTimelineView",
 					"when": "gitlens:enabled"
 				},
+				{
+					"command": "gitlens.showWelcomePage",
+					"when": "gitlens:enabled"
+				},
 				{
 					"command": "gitlens.showWorkspacesView",
 					"when": "gitlens:enabled && !gitlens:hasVirtualFolders"
diff --git a/src/constants.commands.generated.ts b/src/constants.commands.generated.ts
@@ -999,6 +999,7 @@ export type ContributedPaletteCommands =
 	| 'gitlens.showTagsView'
 	| 'gitlens.showTimelinePage'
 	| 'gitlens.showTimelineView'
+	| 'gitlens.showWelcomePage'
 	| 'gitlens.showWorkspacesView'
 	| 'gitlens.showWorktreesView'
 	| 'gitlens.startWork'
diff --git a/src/constants.views.ts b/src/constants.views.ts
@@ -37,7 +37,7 @@ export type GroupableTreeViewTypes = Extract<
 >;
 export type GroupableTreeViewIds<T extends GroupableTreeViewTypes = GroupableTreeViewTypes> = TreeViewIds<T>;
 
-export type WebviewTypes = 'composer' | 'graph' | 'patchDetails' | 'settings' | 'timeline';
+export type WebviewTypes = 'composer' | 'graph' | 'patchDetails' | 'settings' | 'timeline' | 'welcome';
 export type WebviewIds = `gitlens.${WebviewTypes}`;
 
 export type WebviewViewTypes = 'commitDetails' | 'graph' | 'graphDetails' | 'home' | 'patchDetails' | 'timeline';
diff --git a/src/container.ts b/src/container.ts
@@ -78,6 +78,7 @@ import { registerTimelineWebviewCommands, registerTimelineWebviewPanel } from '.
 import { RebaseEditorProvider } from './webviews/rebase/rebaseEditor';
 import { registerSettingsWebviewCommands, registerSettingsWebviewPanel } from './webviews/settings/registration';
 import { WebviewsController } from './webviews/webviewsController';
+import { registerWelcomeWebviewPanel } from './webviews/welcome/registration';
 
 export type Environment = 'dev' | 'staging' | 'production';
 
@@ -257,6 +258,9 @@ export class Container {
 		this._disposables.push(settingsPanels);
 		this._disposables.push(registerSettingsWebviewCommands(settingsPanels));
 
+		const welcomePanels = registerWelcomeWebviewPanel(webviews);
+		this._disposables.push(welcomePanels);
+
 		this._disposables.push(new ViewFileDecorationProvider());
 
 		const patchDetailsPanels = registerPatchDetailsWebviewPanel(webviews);
diff --git a/src/extension.ts b/src/extension.ts
@@ -347,6 +347,12 @@ async function showWhatsNew(
 	if (previousVersion == null) {
 		Logger.log(`GitLens first-time install; window.focused=${window.state.focused}`);
 
+		// Show welcome webview on first install for IDEs that don't support walkthroughs (e.g., Cursor)
+		// For IDEs that support walkthroughs, the walkthrough will be shown instead
+		if (window.state.focused && !container.walkthrough.isWalkthroughSupported) {
+			void executeCommand('gitlens.showWelcomePage');
+		}
+
 		return;
 	}
 
diff --git a/src/webviews/apps/welcome/context.ts b/src/webviews/apps/welcome/context.ts
@@ -0,0 +1,4 @@
+import { createContext } from '@lit/context';
+import type { State } from '../../welcome/protocol';
+
+export const stateContext = createContext<State>('state');
diff --git a/src/webviews/apps/welcome/stateProvider.ts b/src/webviews/apps/welcome/stateProvider.ts
@@ -0,0 +1,16 @@
+import { ContextProvider } from '@lit/context';
+import type { IpcMessage } from '../../protocol';
+import type { State } from '../../welcome/protocol';
+import type { ReactiveElementHost } from '../shared/appHost';
+import { StateProviderBase } from '../shared/stateProviderBase';
+import { stateContext } from './context';
+
+export class WelcomeStateProvider extends StateProviderBase<State['webviewId'], State, typeof stateContext> {
+	protected override createContextProvider(state: State): ContextProvider<typeof stateContext, ReactiveElementHost> {
+		return new ContextProvider(this.host, { context: stateContext, initialValue: state });
+	}
+
+	protected override onMessageReceived(_msg: IpcMessage): void {
+		// Welcome webview doesn't need to handle any messages
+	}
+}
diff --git a/src/webviews/apps/welcome/welcome.html b/src/webviews/apps/welcome/welcome.html
@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<style nonce="#{cspNonce}">
+			@font-face {
+				font-family: 'codicon';
+				font-display: block;
+				src: url('#{webroot}/codicon.ttf?79130123c9d3674a686cf03962523e8a') format('truetype');
+			}
+			@font-face {
+				font-family: 'glicons';
+				font-display: block;
+				src: url('#{root}/dist/glicons.woff2?d3b316716ee1329763a193a20834cd0a') format('woff2');
+			}
+		</style>
+	</head>
+
+	<body
+		class="preload"
+		data-placement="#{placement}"
+		data-vscode-context='{ "webview": "#{webviewId}", "webviewInstance": "#{webviewInstanceId}" }'
+	>
+		<gl-welcome-app name="WelcomeView" placement="#{placement}" bootstrap="#{state}"></gl-welcome-app>
+	</body>
+</html>
diff --git a/src/webviews/apps/welcome/welcome.scss b/src/webviews/apps/welcome/welcome.scss
@@ -0,0 +1 @@
+@use '../shared/styles/theme';
diff --git a/src/webviews/apps/welcome/welcome.ts b/src/webviews/apps/welcome/welcome.ts
@@ -0,0 +1,95 @@
+/*global*/
+import './welcome.scss';
+import { html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { State } from '../../welcome/protocol';
+import { GlAppHost } from '../shared/appHost';
+import { scrollableBase } from '../shared/components/styles/lit/base.css';
+import type { LoggerContext } from '../shared/contexts/logger';
+import type { HostIpc } from '../shared/ipc';
+import { WelcomeStateProvider } from './stateProvider';
+import '../shared/components/gitlens-logo';
+
+@customElement('gl-welcome-app')
+export class GlWelcomeApp extends GlAppHost<State> {
+	static override styles = [scrollableBase];
+
+	protected override createStateProvider(
+		bootstrap: string,
+		ipc: HostIpc,
+		logger: LoggerContext,
+	): WelcomeStateProvider {
+		return new WelcomeStateProvider(this, bootstrap, ipc, logger);
+	}
+
+	override render(): unknown {
+		return html`
+			<div class="welcome scrollable">
+				<div>
+					<h1><gitlens-logo></gitlens-logo></h1>
+					<p>Supercharge Git in Cursor with GitLens</p>
+				</div>
+
+				<div>
+					<h2>🚀 Getting Started</h2>
+					<p>
+						GitLens is now installed and ready to help you visualize code authorship, navigate Git history,
+						and collaborate more effectively.
+					</p>
+				</div>
+
+				<div>
+					<h2>✨ Key Features</h2>
+					<ul>
+						<li>
+							<span>📝</span>
+							<strong>Blame Annotations</strong> - See who changed each line and when
+						</li>
+						<li>
+							<span>📊</span>
+							<strong>Commit Graph</strong> - Visualize your repository's history
+						</li>
+						<li>
+							<span>🔍</span>
+							<strong>File History</strong> - Track changes to any file over time
+						</li>
+						<li>
+							<span>🌿</span>
+							<strong>Branch Management</strong> - Easily manage branches and remotes
+						</li>
+						<li>
+							<span>🤖</span>
+							<strong>AI Features</strong> - Generate commit messages and explanations
+						</li>
+					</ul>
+				</div>
+
+				<div>
+					<h2>🎯 Next Steps</h2>
+					<ul>
+						<li>
+							<span>1.</span>
+							Open the <strong>GitLens Home</strong> view in the sidebar to see your active work
+						</li>
+						<li>
+							<span>2.</span>
+							Try the <strong>Commit Graph</strong> to visualize your repository
+						</li>
+						<li>
+							<span>3.</span>
+							Hover over any line to see <strong>inline blame</strong> information
+						</li>
+						<li>
+							<span>4.</span>
+							Explore the <strong>Command Palette</strong> (Cmd/Ctrl+Shift+P) and search for "GitLens"
+						</li>
+					</ul>
+				</div>
+
+				<div>
+					<p>GitLens ${this.state?.version ?? ''} is ready to use!</p>
+				</div>
+			</div>
+		`;
+	}
+}
diff --git a/src/webviews/welcome/protocol.ts b/src/webviews/welcome/protocol.ts
@@ -0,0 +1,7 @@
+import type { IpcScope, WebviewState } from '../protocol';
+
+export const scope: IpcScope = 'welcome';
+
+export interface State extends WebviewState<'gitlens.welcome'> {
+	version: string;
+}
diff --git a/src/webviews/welcome/registration.ts b/src/webviews/welcome/registration.ts
@@ -0,0 +1,34 @@
+import { ViewColumn } from 'vscode';
+import type { WebviewPanelsProxy, WebviewsController } from '../webviewsController';
+import type { State } from './protocol';
+
+export type WelcomeWebviewShowingArgs = [];
+
+export function registerWelcomeWebviewPanel(
+	controller: WebviewsController,
+): WebviewPanelsProxy<'gitlens.welcome', WelcomeWebviewShowingArgs, State> {
+	return controller.registerWebviewPanel<'gitlens.welcome', State, State, WelcomeWebviewShowingArgs>(
+		{ id: 'gitlens.showWelcomePage' },
+		{
+			id: 'gitlens.welcome',
+			fileName: 'welcome.html',
+			iconPath: 'images/gitlens-icon.png',
+			title: 'Welcome to GitLens',
+			contextKeyPrefix: `gitlens:webview:welcome`,
+			trackingFeature: 'welcomeWebview',
+			type: 'welcome',
+			plusFeature: false,
+			column: ViewColumn.Active,
+			webviewHostOptions: {
+				retainContextWhenHidden: false,
+				enableFindWidget: false,
+			},
+		},
+		async (container, host) => {
+			const { WelcomeWebviewProvider } = await import(
+				/* webpackChunkName: "webview-welcome" */ './welcomeWebview'
+			);
+			return new WelcomeWebviewProvider(container, host);
+		},
+	);
+}
diff --git a/src/webviews/welcome/welcomeWebview.ts b/src/webviews/welcome/welcomeWebview.ts
@@ -0,0 +1,41 @@
+import { Disposable } from 'vscode';
+import type { WebviewTelemetryContext } from '../../constants.telemetry';
+import type { Container } from '../../container';
+import type { WebviewHost, WebviewProvider } from '../webviewProvider';
+import type { State } from './protocol';
+import type { WelcomeWebviewShowingArgs } from './registration';
+
+export class WelcomeWebviewProvider implements WebviewProvider<State, State, WelcomeWebviewShowingArgs> {
+	private readonly _disposable: Disposable;
+
+	constructor(
+		private readonly container: Container,
+		private readonly host: WebviewHost<'gitlens.welcome'>,
+	) {
+		this.host.title = 'Welcome to GitLens';
+		this._disposable = Disposable.from();
+	}
+
+	dispose(): void {
+		this._disposable.dispose();
+	}
+
+	getTelemetryContext(): WebviewTelemetryContext {
+		return {
+			...this.host.getTelemetryContext(),
+		};
+	}
+
+	includeBootstrap(): State {
+		return this.getState();
+	}
+
+	private getState(): State {
+		return {
+			webviewId: 'gitlens.welcome',
+			webviewInstanceId: this.host.instanceId,
+			timestamp: Date.now(),
+			version: this.container.version,
+		};
+	}
+}
diff --git a/webpack.config.mjs b/webpack.config.mjs
@@ -369,6 +369,7 @@ function getWebviewsConfigs(mode, env) {
 				settings: { entry: './settings/settings.ts' },
 				timeline: { entry: './plus/timeline/timeline.ts', plus: true },
 				patchDetails: { entry: './plus/patchDetails/patchDetails.ts', plus: true },
+				welcome: { entry: './welcome/welcome.ts' },
 			},
 			{},
 			mode,
