Svelte 5 migration

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
+{
+	"name": "Node.js & TypeScript",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
+	"features": {
+		"ghcr.io/devcontainers/features/node:1": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"svelte.svelte-vscode",
+				"esbenp.prettier-vscode",
+				"vitest.explorer",
+				"github.vscode-github-actions",
+				"ms-vscode.vscode-typescript-next"
+			]
+		}
+	}
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "yarn install",
+	// Configure tool-specific properties.
+	// "customizations": {},
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

.gitignore

@@ -1,9 +1,7 @@
 .DS_Store
 node_modules
-/build
-/dist
-/.svelte-kit
-/package
+.pnpm-store
+.svelte-kit
 .env
 .env.*
 !.env.example

README.md

@@ -1,19 +1,18 @@
 # svelte-plausible-analytics
 
-Add Plausible Analytics to a SvelteKit app and track analytics and custom events.
+Add Plausible Analytics to a SvelteKit app to track analytics and custom events.
 
-*Important* - requires a [Plausible Analytics](https://plausible.io/) account.
-All events require custom goals to be configured in the Plausible Analytics dashboard.
+**Important:** `svelte-plausible-analytics` requires a [Plausible Analytics](https://plausible.io/) account or a [self-hosted](https://plausible.io/docs/self-hosting) Plausible instance.
 
-## Install the package
+## Installation
 
-```bash
+```shell
 npm i --save-dev @accuser/svelte-plausible-analytics
 ```
 
-## Examples
+## Usage
 
-Add Plausible Analytics to the root layout to track page views.
+It is recommended to add the `<PlausibleAnalytics />` component to the root layout of your app. In most cases this will be `src/routes/+layout.svelte`.
 
 ```svelte
 <script>
@@ -25,28 +24,86 @@ Add Plausible Analytics to the root layout to track page views.
 <slot />
 ```
 
-Track analytics events:
+As Plausible only requires your domain during setup to function correctly, you can use `<PlausibleAnalytics />` without any further configuration. `svelte-plausible-analytics` automatically sets the `data-domain` attribute to your domain. You can change this behavior through its [props](#props).
+
+### Props
+
+You can see the full list of props on [GitHub](https://github.com/accuser/svelte-plausible-analytics/blob/main/src/lib/PlausibleAnalytics.svelte) or through IntelliSense in your IDE. In general, the props allow you to configure the [required script attributes](https://plausible.io/docs/plausible-script) and to enable [enhanced measurements](https://plausible.io/docs/script-extensions).
+
+### Events
+
+Goals and custom events allow you to track actions that you want your visitors to take on your site. With `svelte-plausible-analytics` you can track [custom event goals](https://plausible.io/docs/custom-event-goals). Import `pa` from `@accuser/svelte-plausible-analytics` to have access to the `addEvent` method and some other helper functions.
+
+Here's an example on how you'd track a `login` event:
+
+1. [Create a custom event goal](https://plausible.io/docs/custom-event-goals#3-create-a-custom-event-goal-in-your-plausible-account) in your dashboard with the name `login`
+1. Import the `pa` namespace
+    ```svelte
+    <script>
+      import { pa } from '@accuser/svelte-plausible-analytics';
+    </script>
+
+    <button>Login</button>
+    ```
+1. Use the `addEvent` method to track an event. The first argument is the event name (required), the second argument is optional and can be used to [attach custom properties](https://plausible.io/docs/custom-props/for-custom-events#2-using-the-manual-method).
+    ```svelte
+    <script>
+      import { pa } from '@accuser/svelte-plausible-analytics';
+    </script>
+
+    <button on:click={pa.addEvent('login')}>Login</button>
+    ```
+
+For common events `@accuser/svelte-plausible-analytics` provides helper functions to enforce certain props. Feel free to only use `addEvent` if they don't fit your requirements. As an example, you can use the `login` method like so:
 
 ```svelte
 <script>
   import { pa } from '@accuser/svelte-plausible-analytics';
-
-  const { login } = pa;
 </script>
 
-<button on:click={login('Button')}>Click to login!</button>
+<button on:click={pa.login('CTA')}>Login</button>
 ```
 
-Track custom events:
+Behind the scenes this helper function sends the event with the name `login` and a custom property of `method: 'CTA'`. You can find all helper functions on [GitHub](https://github.com/accuser/svelte-plausible-analytics/blob/main/src/lib/store.ts) or through IntelliSense in your IDE.
+
+**Important:** You need to create a custom event goal in your dashboard when using any of the event methods.
+
+## Examples
+
+Here are some further usage examples. If you have a snippet that you'd think might be helpful for others, please send them in through a pull request!
+
+### 404 page
+
+File: `src/routes/+error.svelte`
 
 ```svelte
 <script>
-  import { pa } from '@accuser/svelte-plausible-analytics';
+	import { pa } from '@accuser/svelte-plausible-analytics';
+	import { page } from '$app/stores';
+
+	if ($page.status === 404) {
+		pa.addEvent('404', {
+			props: {
+				path: $page.url.pathname,
+			},
+		})
+	}
+</script>
+```
 
-  const { addEvent } = pa;
+### Using a proxy
+
+You can [proxy your script](https://plausible.io/docs/proxy/introduction) to deal with adblockers. You'll want to set the `apiHost` prop to your domain.
+
+File: `src/routes/+layout.svelte`
+
+```svelte
+<script>
+	import { PlausibleAnalytics } from '@accuser/svelte-plausible-analytics';
+	import { page } from '$app/stores';
 </script>
 
-<button on:click={addEvent('click')}>Click me!</button>
+<PlausibleAnalytics apiHost={`${$page.url.protocol}//${$page.url.host}`} />
 ```
 
 ## Contributors

package.json

@@ -8,7 +8,7 @@
 		"svelte",
 		"sveltekit"
 	],
-	"homepage": "https://github.com/accuser/svelte-plausible-analytics/README.md",
+	"homepage": "https://github.com/accuser/svelte-plausible-analytics",
 	"bugs": {
 		"url": "https://github.com/accuser/svelte-plausible-analytics/issues"
 	},
@@ -17,6 +17,20 @@
 		"name": "Matthew Gibbons",
 		"url": "https://github.com/accuser"
 	},
+	"contributors": [
+		{
+			"name": "Jeffrey Palmer",
+			"url": "https://github.com/JeffreyPalmer"
+		},
+		{
+			"name": "Dan Grebb",
+			"url": "https://github.com/dgrebb"
+		},
+		{
+			"name": "Lennart",
+			"url": "https://github.com/LekoArts"
+		}
+	],
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/accuser/svelte-plausible-analytics.git"
@@ -27,10 +41,9 @@
 		"preview": "vite preview",
 		"package": "svelte-kit sync && svelte-package && publint",
 		"prepublishOnly": "npm run package",
-		"test": "playwright test",
+		"test": "vitest",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-		"test:unit": "vitest",
 		"lint": "prettier --plugin-search-dir . --check . && eslint .",
 		"format": "prettier --plugin-search-dir . --write ."
 	},
@@ -46,31 +59,35 @@
 		"!dist/**/*.spec.*"
 	],
 	"peerDependencies": {
-		"@sveltejs/kit": "^1.30.3 || ^2.0.0",
-		"svelte": "^4.2.8"
+		"svelte": "^5.0.0-next.1"
 	},
 	"devDependencies": {
-		"@playwright/test": "^1.40.1",
-		"@sveltejs/adapter-auto": "^3.0.0",
-		"@sveltejs/kit": "^2.0.0",
-		"@sveltejs/package": "^2.2.3",
-		"@typescript-eslint/eslint-plugin": "^6.14.0",
-		"@typescript-eslint/parser": "^6.14.0",
-		"eslint": "^8.56.0",
+		"@sveltejs/adapter-auto": "^3.3.1",
+		"@sveltejs/kit": "^2.11.1",
+		"@sveltejs/package": "^2.3.7",
+		"@sveltejs/vite-plugin-svelte": "5.0.2",
+		"@testing-library/jest-dom": "^6.6.3",
+		"@types/jsdom": "^21.1.7",
+		"@typescript-eslint/eslint-plugin": "^8.18.0",
+		"@typescript-eslint/parser": "^8.18.0",
+		"autoprefixer": "^10.4.20",
+		"eslint": "^9.16.0",
 		"eslint-config-prettier": "^9.1.0",
-		"eslint-plugin-svelte": "^2.35.1",
-		"prettier": "^3.1.1",
-		"prettier-plugin-svelte": "^3.1.2",
-		"publint": "^0.2.6",
-		"svelte": "^4.2.8",
-		"svelte-check": "^3.6.2",
-		"tslib": "^2.6.2",
-		"typescript": "^5.3.3",
-		"vite": "^5.0.10",
-		"vitest": "^1.0.4",
-		"@sveltejs/vite-plugin-svelte": "^3.0.1"
+		"eslint-plugin-svelte": "^2.46.1",
+		"jsdom": "^25.0.1",
+		"plausible-tracker": "^0.3.9",
+		"prettier": "^3.4.2",
+		"prettier-plugin-svelte": "^3.3.2",
+		"publint": "^0.2.12",
+		"svelte": "5.12.0",
+		"svelte-check": "^4.1.1",
+		"tslib": "^2.8.1",
+		"typescript": "^5.7.2",
+		"typescript-eslint": "^8.18.0",
+		"vite": "^6.0.3",
+		"vitest": "^2.1.8"
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"type": "module"
-}
+}