Skip to content

Commit 5c9a7aa

Browse files
harlan-zwharlan-zw
authored
feat!: plausible script updates (#534)
1 parent 1ea3722 commit 5c9a7aa

File tree

5 files changed

+311
-27
lines changed

5 files changed

+311
-27
lines changed

‎docs/content/scripts/analytics/plausible-analytics.md‎

Lines changed: 68 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,10 @@ export default defineNuxtConfig({
2525
scripts: {
2626
registry: {
2727
plausibleAnalytics: {
28-
domain: 'YOUR_DOMAIN'
28+
// Get this from your Plausible script URL:
29+
// https://plausible.io/js/pa-gYyxvZhkMzdzXBAtSeSNz.js
30+
// ^^^^^^^^^^^^^^^^^^^^^^^^^^
31+
scriptId: 'gYyxvZhkMzdzXBAtSeSNz'
2932
}
3033
}
3134
}
@@ -38,7 +41,7 @@ export default defineNuxtConfig({
3841
scripts: {
3942
registry: {
4043
plausibleAnalytics: {
41-
domain: 'YOUR_DOMAIN',
44+
scriptId: 'YOUR_SCRIPT_ID',
4245
}
4346
}
4447
}
@@ -59,8 +62,8 @@ export default defineNuxtConfig({
5962
scripts: {
6063
plausibleAnalytics: {
6164
// .env
62-
// NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_DOMAIN=<your-domin>
63-
domain: ''
65+
// NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_SCRIPT_ID=<your-script-id>
66+
scriptId: ''
6467
},
6568
},
6669
},
@@ -75,8 +78,11 @@ export default defineNuxtConfig({
7578
The `useScriptPlausibleAnalytics` composable lets you have fine-grain control over when and how Plausible Analytics is loaded on your site.
7679

7780
```ts
81+
// New October 2025 format
7882
const plausible = useScriptPlausibleAnalytics({
79-
domain: 'YOUR_DOMAIN'
83+
// Extract from: https://plausible.io/js/pa-gYyxvZhkMzdzXBAtSeSNz.js
84+
// ^^^^^^^^^^^^^^^^^^^^^^^^^^
85+
scriptId: 'gYyxvZhkMzdzXBAtSeSNz'
8086
})
8187
```
8288

@@ -112,10 +118,63 @@ export interface PlausibleAnalyticsApi {
112118
You must provide the options when setting up the script for the first time.
113119

114120
```ts
115-
export const PlausibleAnalyticsOptions = object({
116-
domain: string(), // required
117-
extension: optional(union([union(extensions), array(union(extensions))])),
118-
})
121+
export interface PlausibleAnalyticsOptions {
122+
/**
123+
* Unique script ID for your site (recommended - new format as of October 2025)
124+
* Extract from: <script src="https://plausible.io/js/pa-{scriptId}.js"></script>
125+
*/
126+
scriptId?: string
127+
/** Custom properties to track with every pageview */
128+
customProperties?: Record<string, any>
129+
/** Custom tracking endpoint URL */
130+
endpoint?: string
131+
/** Configure file download tracking */
132+
fileDownloads?: {
133+
fileExtensions?: string[]
134+
}
135+
/** Enable hash-based routing for single-page apps */
136+
hashBasedRouting?: boolean
137+
/** Set to false to manually trigger pageviews */
138+
autoCapturePageviews?: boolean
139+
/** Enable tracking on localhost */
140+
captureOnLocalhost?: boolean
141+
/** Enable form submission tracking */
142+
trackForms?: boolean
143+
}
144+
```
145+
146+
```ts
147+
export interface PlausibleAnalyticsDeprecatedOptions {
148+
/**
149+
* Your site domain
150+
* @deprecated Use `scriptId` instead (new October 2025 format)
151+
*/
152+
domain?: string
153+
/**
154+
* Script extensions for additional features
155+
* @deprecated Use init options like `hashBasedRouting`, `captureOnLocalhost`, etc. instead
156+
*/
157+
extension?: 'hash' | 'outbound-links' | 'file-downloads' | 'tagged-events' | 'revenue' | 'pageview-props' | 'compat' | 'local' | 'manual'
158+
}
159+
160+
```
161+
162+
**Note:** The `scriptId` is found in your Plausible dashboard under **Site Installation** in your site settings.
163+
164+
**Extracting your Script ID:**
165+
166+
Plausible provides you with a script tag like this:
167+
168+
```html
169+
<script async src="https://plausible.io/js/pa-gYyxvZhkMzdzXBAtSeSNz.js"></script>
170+
```
171+
172+
Your `scriptId` is the part after `pa-` and before `.js`:
173+
174+
```ts
175+
scriptId: 'gYyxvZhkMzdzXBAtSeSNz'
176+
// ^^^^^^^^^^^^^^^^^^^^^^^
177+
// Extract from: pa-{scriptId}.js
119178
```
120179

121180
## Example

‎playground/pages/index.vue‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,12 @@ const analytics = registryScripts
7171
logo: registryScripts.find(s => s.label === 'Google Analytics')?.logo,
7272
registryScript: null,
7373
},
74+
{
75+
name: 'Plausible Analytics v2 (Oct 2025)',
76+
path: '/third-parties/plausible-analytics-v2',
77+
logo: registryScripts.find(s => s.label === 'Plausible Analytics')?.logo,
78+
registryScript: null,
79+
},
7480
])
7581
7682
const pixels = registryScripts

‎playground/pages/third-parties/plausible-analytics-v2.vue‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<script lang="ts" setup>
2+
import { ref, useHead } from '#imports'
3+
4+
useHead({
5+
title: 'Plausible v2',
6+
})
7+
8+
// New October 2025 format with scriptId
9+
const { status, proxy } = useScriptPlausibleAnalytics({
10+
scriptId: 'gYyxvZhkMzdzXBAtSeSNz',
11+
captureOnLocalhost: true,
12+
scriptOptions: {
13+
trigger: 'onNuxtReady',
14+
},
15+
})
16+
17+
const clicks = ref(0)
18+
19+
function trackPageView() {
20+
proxy.plausible('404', { props: { path: '/404' } })
21+
}
22+
23+
async function clickHandler() {
24+
clicks.value++
25+
proxy.plausible('test', { props: { clicks: clicks.value } })
26+
}
27+
</script>
28+
29+
<template>
30+
<div class="space-y-6">
31+
<div>
32+
<h1 class="text-3xl font-bold">
33+
Plausible Analytics v2 (October 2025)
34+
</h1>
35+
<p class="text-gray-600 mt-2">
36+
New format with unique script ID and plausible.init() configuration.
37+
</p>
38+
</div>
39+
40+
<div class="space-y-4">
41+
<div>
42+
<span class="font-medium">Status:</span>
43+
<span class="ml-2 px-2 py-1 rounded text-sm" :class="status === 'loaded' ? 'bg-green-100 text-green-700' : 'bg-gray-100 text-gray-700'">
44+
{{ status }}
45+
</span>
46+
</div>
47+
48+
<div class="bg-blue-50 border border-blue-200 rounded p-4">
49+
<h3 class="font-semibold mb-2">
50+
Configuration
51+
</h3>
52+
<pre class="text-xs bg-white p-2 rounded overflow-x-auto">scriptId: 'gYyxvZhkMzdzXBAtSeSNz'
53+
captureOnLocalhost: true</pre>
54+
</div>
55+
56+
<div class="flex gap-3">
57+
<UButton
58+
:disabled="status !== 'loaded'"
59+
@click="trackPageView"
60+
>
61+
Track 404 Page View
62+
</UButton>
63+
64+
<UButton
65+
:disabled="status !== 'loaded'"
66+
@click="clickHandler"
67+
>
68+
Track Custom Event ({{ clicks }})
69+
</UButton>
70+
</div>
71+
</div>
72+
</div>
73+
</template>

‎playground/pages/third-parties/plausible-analytics.vue‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,20 @@ useHead({
66
})
77
88
// composables return the underlying api as a proxy object and the script state
9+
// Using legacy domain format for playground - in production use scriptId instead
910
const { status, proxy } = useScriptPlausibleAnalytics({
1011
domain: 'scripts.nuxt.com',
11-
extension: 'local',
12+
captureOnLocalhost: true, // New October 2025 init option
1213
scriptOptions: {
1314
trigger: 'onNuxtReady',
1415
},
1516
})
17+
// Example with new scriptId format:
18+
// const { status, proxy } = useScriptPlausibleAnalytics({
19+
// scriptId: 'YOUR_SCRIPT_ID', // Get from Plausible dashboard
20+
// captureOnLocalhost: true,
21+
// scriptOptions: { trigger: 'onNuxtReady' },
22+
// })
1623
1724
const clicks = ref(0)
1825

0 commit comments

Comments
 (0)