[@astrojs/vercel] Individually enable Speed Insights and Web Analytics

.changeset/sixty-teachers-tap.md

@@ -0,0 +1,26 @@
+---
+'@astrojs/vercel': major
+---
+
+Enable Vercel Speed Insights and Vercel Web Analytics individually.
+Deprecates the `analytics` property in `astro.config.mjs` in favor of `speedInsights` and `webAnalytics`.
+
+If you're using the `analytics` property, you'll need to update your config to use the new properties:
+
+```diff
+// astro.config.mjs
+export default defineConfig({
+	adapter: vercel({
+-   analytics: true,
++		webAnalytics: {
++			enabled: true
++		},
++		speedInsights: {
++			enabled: true
++		}
+	})
+});
+```
+
+Allow configuration of Web Analytics with all available configuration options.
+Bumps @vercel/analytics package to the latest version.

packages/integrations/vercel/README.md

@@ -85,13 +85,56 @@ vercel deploy --prebuilt
 
 To configure this adapter, pass an object to the `vercel()` function call in `astro.config.mjs`:
 
-### analytics
+### Web Analytics
 
-**Type:** `boolean`<br>
-**Available for:** Serverless, Static<br>
-**Added in:** `@astrojs/vercel@3.1.0`
+**Type:** `VercelWebAnalyticsConfig`<br>
+**Available for:** Serverless, Edge, Static<br>
+**Added in:** `@astrojs/vercel@3.8.0`
+
+You can enable [Vercel Web Analytics](https://vercel.com/docs/concepts/analytics) by setting `webAnalytics: { enabled: true }`. This will inject Vercel’s tracking scripts into all of your pages.
+You can also pass [configuration options](https://vercel.com/docs/concepts/analytics/package) like `mode` and `debug` via the `config` property inside `webAnalytics`.
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel/serverless';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel({
+    webAnalytics: {
+      enabled: true,
+    },
+  }),
+});
+```
+
+#### `beforeSend`
+
+`beforeSend` is a function that can modify analytics event data before it's sent to Vercel.
+
+Define this function in a separate file at the root of your project called `vercel-web-analytics.ts` (or `vercel-web-analytics.js` if you're not using TypeScript).
 
-You can enable [Vercel Analytics](https://vercel.com/analytics) (including Web Vitals and Audiences) by setting `analytics: true`. This will inject Vercel’s tracking scripts into all your pages.
+```ts
+// vercel-web-analytics.ts
+import type { VercelWebAnalyticsBeforeSend } from '@astrojs/vercel';
+
+export const beforeSend: VercelWebAnalyticsBeforeSend = (event) => {
+  // Ignore all events that have a `/private` inside the URL
+  if (event.url.includes('/private')) {
+    return null;
+  }
+  return event;
+};
+```
+
+### Speed Insights
+
+You can enable [Vercel Speed Insights](https://vercel.com/docs/concepts/speed-insights) by setting `speedInsights: { enabled: true }`. This will collect and send Web Vital data to Vercel.
+
+**Type:** `VercelSpeedInsightsConfig`<br>
+**Available for:** Serverless, Edge, Static<br>
+**Added in:** `@astrojs/vercel@3.8.0`
 
 ```js
 // astro.config.mjs
@@ -101,7 +144,9 @@ import vercel from '@astrojs/vercel/serverless';
 export default defineConfig({
   output: 'server',
   adapter: vercel({
-    analytics: true,
+    speedInsights: {
+      enabled: true,
+    },
   }),
 });
 ```

packages/integrations/vercel/package.json

@@ -22,7 +22,7 @@
     "./serverless": "./dist/serverless/adapter.js",
     "./serverless/entrypoint": "./dist/serverless/entrypoint.js",
     "./static": "./dist/static/adapter.js",
-    "./analytics": "./dist/analytics.js",
+    "./speed-insights": "./dist/speed-insights.js",
     "./build-image-service": "./dist/image/build-service.js",
     "./dev-image-service": "./dist/image/dev-service.js",
     "./package.json": "./package.json"

packages/integrations/vercel/src/lib/speed-insights.ts

@@ -0,0 +1,15 @@
+import { exposeEnv } from './env';
+
+export type VercelSpeedInsightsConfig = {
+	enabled: boolean;
+};
+
+export function getSpeedInsightsViteConfig(enabled?: boolean) {
+	if (enabled) {
+		return {
+			define: exposeEnv(['VERCEL_ANALYTICS_ID']),
+		};
+	}
+
+	return {};
+}

packages/integrations/vercel/src/lib/web-analytics.ts

@@ -0,0 +1,76 @@
+import { AstroError } from 'astro/errors';
+import type { AnalyticsProps } from '@vercel/analytics';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'node:fs';
+import type { AstroIntegrationLogger } from 'astro';
+
+export type VercelWebAnalyticsConfig = {
+	enabled: boolean;
+	config?: Omit<AnalyticsProps, 'beforeSend'>;
+};
+
+async function getWebAnalyticsFunctions({
+	root,
+	logger,
+}: {
+	root: URL;
+	logger: AstroIntegrationLogger;
+}) {
+	const tsPath = fileURLToPath(new URL('./vercel-web-analytics.ts', root));
+	const jsPath = fileURLToPath(new URL('./vercel-web-analytics.js', root));
+
+	const tsFileExists = existsSync(tsPath);
+	const jsFileExists = existsSync(jsPath);
+
+	if (tsFileExists && jsFileExists) {
+		logger.warn(
+			`@astrojs/vercel: Both \`vercel-web-analytics.ts\` and \`vercel-web-analytics.js\` exist. Using \`vercel-web-analytics.ts\`.`
+		);
+	}
+
+	if (!tsFileExists && !jsFileExists) {
+		logger.debug(
+			`@astrojs/vercel: \`vercel-web-analytics.ts\` or \`vercel-web-analytics.js\` not found.`
+		);
+
+		return {
+			beforeSend: undefined,
+		};
+	}
+
+	const functions = await import(
+		tsFileExists ? /* @vite-ignore */ tsPath : /* @vite-ignore */ jsPath
+	);
+
+	if (typeof functions.beforeSend !== 'function') {
+		throw new AstroError(
+			`@astrojs/vercel: \`vercel-web-analytics.${
+				tsFileExists ? 'ts' : 'js'
+			}\` must export a \`beforeSend\` function.`
+		);
+	}
+
+	return {
+		beforeSend: functions.beforeSend,
+	};
+}
+
+export async function getInjectableWebAnalyticsContent({
+	config,
+	astro,
+}: {
+	config: Omit<AnalyticsProps, 'beforeSend'> | undefined;
+	astro: {
+		root: URL;
+		logger: AstroIntegrationLogger;
+	};
+}) {
+	const { beforeSend } = await getWebAnalyticsFunctions(astro);
+
+	return `import { inject } from '@vercel/analytics';
+		inject({
+			mode: ${config?.mode},
+			beforeSend: ${beforeSend},
+			debug: ${config?.debug}
+		});`;
+}

packages/integrations/vercel/src/serverless/adapter.ts

@@ -10,11 +10,18 @@ import glob from 'fast-glob';
 import { basename } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { defaultImageConfig, getImageConfig, type VercelImageConfig } from '../image/shared.js';
-import { exposeEnv } from '../lib/env.js';
 import { getVercelOutput, removeDir, writeJson } from '../lib/fs.js';
 import { copyDependenciesToFunction } from '../lib/nft.js';
 import { getRedirects } from '../lib/redirects.js';
 import { generateEdgeMiddleware } from './middleware.js';
+import {
+	getInjectableWebAnalyticsContent,
+	type VercelWebAnalyticsConfig,
+} from '../lib/web-analytics.js';
+import {
+	getSpeedInsightsViteConfig,
+	type VercelSpeedInsightsConfig,
+} from '../lib/speed-insights.js';
 
 const PACKAGE_NAME = '@astrojs/vercel/serverless';
 export const ASTRO_LOCALS_HEADER = 'x-astro-locals';
@@ -59,19 +66,26 @@ function getAdapter({
 }
 
 export interface VercelServerlessConfig {
+	/**
+	 * @deprecated
+	 */
+	analytics?: boolean;
+	webAnalytics?: VercelWebAnalyticsConfig;
+	speedInsights?: VercelSpeedInsightsConfig;
 	includeFiles?: string[];
 	excludeFiles?: string[];
-	analytics?: boolean;
 	imageService?: boolean;
 	imagesConfig?: VercelImageConfig;
 	edgeMiddleware?: boolean;
 	functionPerRoute?: boolean;
 }
 
 export default function vercelServerless({
+	analytics,
+	webAnalytics,
+	speedInsights,
 	includeFiles,
 	excludeFiles,
-	analytics,
 	imageService,
 	imagesConfig,
 	functionPerRoute = true,
@@ -124,12 +138,32 @@ export default function vercelServerless({
 	return {
 		name: PACKAGE_NAME,
 		hooks: {
-			'astro:config:setup': ({ command, config, updateConfig, injectScript }) => {
-				if (command === 'build' && analytics) {
-					injectScript('page', 'import "@astrojs/vercel/analytics"');
+			'astro:config:setup': async ({ command, config, updateConfig, injectScript, logger }) => {
+				if (webAnalytics?.enabled || analytics) {
+					if (analytics) {
+						logger.warn(
+							`@astrojs/vercel: the \`analytics\` property is deprecated. Please use the new \`webAnalytics\` and \`speedInsights\` properties instead.`
+						);
+					}
+
+					injectScript(
+						'page',
+						await getInjectableWebAnalyticsContent({
+							config: {
+								...(webAnalytics?.config || {}),
+								mode: command === 'dev' ? 'development' : 'production',
+							},
+							astro: {
+								root: config.root,
+								logger,
+							},
+						})
+					);
+				}
+				if (command === 'build' && (speedInsights?.enabled || analytics)) {
+					injectScript('page', 'import "@astrojs/vercel/speed-insights"');
 				}
 				const outDir = getVercelOutput(config.root);
-				const viteDefine = exposeEnv(['VERCEL_ANALYTICS_ID']);
 				updateConfig({
 					outDir,
 					build: {
@@ -138,7 +172,7 @@ export default function vercelServerless({
 						server: new URL('./dist/', config.root),
 					},
 					vite: {
-						define: viteDefine,
+						...getSpeedInsightsViteConfig(speedInsights?.enabled),
 						ssr: {
 							external: ['@vercel/nft'],
 						},

packages/integrations/vercel/src/analytics.ts → packages/integrations/vercel/src/speed-insights.ts

@@ -1,8 +1,7 @@
-import { inject } from '@vercel/analytics';
 import type { Metric } from 'web-vitals';
-import { getCLS, getFCP, getFID, getLCP, getTTFB } from 'web-vitals';
+import { onCLS, onFCP, onFID, onLCP, onTTFB } from 'web-vitals';
 
-const vitalsUrl = 'https://vitals.vercel-analytics.com/v1/vitals';
+const SPEED_INSIGHTS_INTAKE = 'https://vitals.vercel-analytics.com/v1/vitals';
 
 type Options = { path: string; analyticsId: string };
 
@@ -14,7 +13,7 @@ const getConnectionSpeed = () => {
 		: '';
 };
 
-const sendToAnalytics = (metric: Metric, options: Options) => {
+const sendToSpeedInsights = (metric: Metric, options: Options) => {
 	const body = {
 		dsn: options.analyticsId,
 		id: metric.id,
@@ -28,37 +27,39 @@ const sendToAnalytics = (metric: Metric, options: Options) => {
 		type: 'application/x-www-form-urlencoded',
 	});
 	if (navigator.sendBeacon) {
-		navigator.sendBeacon(vitalsUrl, blob);
+		navigator.sendBeacon(SPEED_INSIGHTS_INTAKE, blob);
 	} else
-		fetch(vitalsUrl, {
+		fetch(SPEED_INSIGHTS_INTAKE, {
 			body: blob,
 			method: 'POST',
 			credentials: 'omit',
 			keepalive: true,
 		});
 };
 
-function webVitals() {
+function collectWebVitals() {
 	const analyticsId = (import.meta as any).env.PUBLIC_VERCEL_ANALYTICS_ID;
+
 	if (!analyticsId) {
-		console.error('[Analytics] VERCEL_ANALYTICS_ID not found');
+		console.error('[Speed Insights] VERCEL_ANALYTICS_ID not found');
 		return;
 	}
+
 	const options: Options = { path: window.location.pathname, analyticsId };
+
 	try {
-		getFID((metric) => sendToAnalytics(metric, options));
-		getTTFB((metric) => sendToAnalytics(metric, options));
-		getLCP((metric) => sendToAnalytics(metric, options));
-		getCLS((metric) => sendToAnalytics(metric, options));
-		getFCP((metric) => sendToAnalytics(metric, options));
+		onFID((metric) => sendToSpeedInsights(metric, options));
+		onTTFB((metric) => sendToSpeedInsights(metric, options));
+		onLCP((metric) => sendToSpeedInsights(metric, options));
+		onCLS((metric) => sendToSpeedInsights(metric, options));
+		onFCP((metric) => sendToSpeedInsights(metric, options));
 	} catch (err) {
-		console.error('[Analytics]', err);
+		console.error('[Speed Insights]', err);
 	}
 }
 
 const mode = (import.meta as any).env.MODE as 'development' | 'production';
 
-inject({ mode });
 if (mode === 'production') {
-	webVitals();
+	collectWebVitals();
 }