@ampless/plugin-plausible 0.1.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,97 @@
+> English: [README.md](./README.md)
+>
+
+# @ampless/plugin-plausible
+
+[ampless](https://github.com/heavymoons/ampless) 向け [Plausible Analytics](https://plausible.io/) プラグイン。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+descriptor ベースのプラグイン head 注入 API を使って、公開ページに Plausible 標準の `<script>` スニペットを挿入します。Plausible はプライバシー重視・cookie 不使用の解析サービスで、多くの導入で cookie 同意バナーは不要です。
+
+サイトドメインとスクリプト URL はどちらもデプロイ後 **`/admin/plugins` から編集可能** で、`cms.config.ts` の constructor 引数は初期デフォルトのシードに過ぎません。AWS のデータ権限は不要で、`trust_level` は `untrusted`、公開 Next.js プロセス内で描画時に動きます。
+
+## インストール
+
+```bash
+npm install @ampless/plugin-plausible@alpha
+```
+
+## 設定
+
+`cms.config.ts` に記述します:
+
+```ts
+import { defineConfig } from 'ampless'
+import plausiblePlugin from '@ampless/plugin-plausible'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    plausiblePlugin({
+      // 初期サイトドメイン（Plausible 管理画面に登録した値と一致させる）。
+      // デプロイ後は /admin/plugins から編集可能。
+      // 空文字でプラグインを無効化したまま ship できる。
+      domain: '',
+    }),
+  ],
+})
+```
+
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `domain` | `''` | 初期 Plausible サイトドメイン。例: `example.com`。Plausible 管理画面に登録した値と完全一致させる必要がある — ミスマッチだとページビューが silently drop される。空文字でプラグインを無効化したまま ship できる。 |
+| `scriptUrl` | `'https://plausible.io/js/script.js'` | Plausible スクリプトの URL。self-hosted Plausible を使う場合に上書き（例: `'https://analytics.example.com/js/script.js'`）。admin field は **required** なので値を消すことはできない。plausible.io デフォルトに戻すには admin form の **デフォルトに戻す** を使う。 |
+| `instanceId` | `'plausible'` | script 要素 id と設定保存キーの namespace。同サイトに複数の Plausible site を入れる場合に分ける。 |
+
+## 管理画面から設定を編集する
+
+デプロイ後、両 field は `/admin/plugins` → **Plausible Analytics** で編集できます。
+
+- **サイトドメイン** — 空文字保存で `cms.config.ts` から削除せずに無効化、`example.com` を保存すれば有効化されます
+- **スクリプト URL** — 必須、デフォルトは `https://plausible.io/js/script.js`。self-hosted Plausible に向けたいときに上書き。`required: true` なので値を消すことはできず、plausible.io デフォルトに戻すには admin form の **デフォルトに戻す** を使ってください
+
+変更内容は site-settings の S3 ミラーが反映された後（数秒）に公開サイトに反映されます。
+
+## Plausible にドメインを登録する
+
+1. [Plausible ダッシュボード](https://plausible.io/sites)（または self-hosted Plausible インスタンス）にサインインします。
+2. **Add site** で、ここで設定するのと同じドメインを入力します — 例: `example.com`。Plausible は受信イベントを「登録済みドメイン文字列」で照合するので、admin form の値とダッシュボードの値は文字単位で一致させる必要があります。
+3. ドメインを上の `domain` に設定するか、admin form に貼り付けます。
+
+ドメイン文字列はサイト識別子であって書き込み認証には使われないため、ソースコードにコミットして問題ありません。
+
+## self-hosted Plausible
+
+[Plausible Community Edition](https://github.com/plausible/community-edition) は自前インフラ上にホストできる self-hosted 版です。このプラグインから self-hosted インスタンスを使うには、admin form（または初期 default として `cms.config.ts`）で `scriptUrl` を上書きします:
+
+```ts
+plausiblePlugin({
+  domain: 'example.com',
+  scriptUrl: 'https://analytics.example.com/js/script.js',
+})
+```
+
+plausible.io デフォルトに戻すには admin form の **デフォルトに戻す** をクリックしてください — 保存済み DDB 行が削除され、次のリクエストから manifest default に fallback します。
+
+## 複数インスタンス
+
+各 `plausiblePlugin(...)` 呼び出しは描画 DOM と admin 設定保存の両方で独立した `instanceId` namespace を持ちます:
+
+```ts
+plugins: [
+  plausiblePlugin({ instanceId: 'marketing', domain: 'marketing.example.com' }),
+  plausiblePlugin({ instanceId: 'product',   domain: 'app.example.com' }),
+]
+```
+
+admin form では各 instance が個別パネルとして表示されます。
+
+## トラストレベル
+
+`untrusted`。プラグインは `@ampless/runtime` が検証・描画する head descriptor を返すだけです。DynamoDB、S3、Lambda プロセッサーには一切触れません。
+
+## まだやらないこと
+
+- **CSP nonce 連携** — script descriptor は `nonce` 無しで emit されます。ampless サイトに CSP enforcement を入れる段で別 RFP として middleware → SSR → descriptor の通り道を設計します
+- **Plausible custom event** — ローダーを注入するだけです。custom event はページコード側で標準 Plausible API (`window.plausible(...)`) を呼んでください

package/README.md

@@ -0,0 +1,97 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+>
+
+# @ampless/plugin-plausible
+
+[Plausible Analytics](https://plausible.io/) plugin for [ampless](https://github.com/heavymoons/ampless).
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+Drops the standard Plausible `<script>` snippet onto every public page through the descriptor-based plugin head injection API. Plausible is a privacy-focused, cookie-free analytics service — most deployments don't need a cookie-consent banner to use it.
+
+The site domain and the script URL are both **editable from `/admin/plugins`** after deploy. The constructor arguments in `cms.config.ts` just seed the initial defaults. No AWS data permissions are required; the plugin's `trust_level` is `untrusted` and everything runs at request time inside the public Next.js process.
+
+## Install
+
+```bash
+npm install @ampless/plugin-plausible@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import plausiblePlugin from '@ampless/plugin-plausible'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    plausiblePlugin({
+      // Initial site domain (matches what's registered in Plausible).
+      // Editable from /admin/plugins after deploy. Leave empty to ship
+      // the plugin disabled and turn it on later.
+      domain: '',
+    }),
+  ],
+})
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `domain` | `''` | Initial Plausible site domain, e.g. `example.com`. Must match the value registered in the Plausible dashboard exactly — a mismatch silently drops every pageview. Set to `''` to ship the plugin disabled. |
+| `scriptUrl` | `'https://plausible.io/js/script.js'` | URL of the Plausible script. Override for self-hosted Plausible (e.g. `'https://analytics.example.com/js/script.js'`). The admin field is **required**, so the value can't be cleared — to switch back to the hosted plausible.io URL, use **Reset to default** in the admin form. |
+| `instanceId` | `'plausible'` | Namespace used for the script element id and settings storage key. Set distinct values when registering multiple Plausible sites on the same deployment. |
+
+## Editing settings from the admin UI
+
+After a deploy, both fields live at `/admin/plugins` → **Plausible Analytics**.
+
+- **Site domain** — saving an empty value disables the plugin without removing it from `cms.config.ts`; saving `example.com` enables it.
+- **Script URL** — required, defaults to `https://plausible.io/js/script.js`. Override to point at a self-hosted Plausible install. The field cannot be cleared (`required: true`); use **Reset to default** in the admin form to switch back to the hosted plausible.io URL.
+
+Changes are reflected on the public site after the site-settings S3 mirror finishes (a few seconds).
+
+## Registering your domain with Plausible
+
+1. Sign in to your [Plausible dashboard](https://plausible.io/sites) (or your self-hosted Plausible instance).
+2. **Add site** and enter the same domain you'll configure here — e.g. `example.com`. Plausible matches on the exact registered string when ingesting events, so the value in the admin form must match the dashboard value character-for-character.
+3. Copy the domain into the `domain` option above, or paste it into the admin form.
+
+The domain string is safe to commit to source control — it's just the site identifier and doesn't authenticate writes.
+
+## Self-hosted Plausible
+
+[Plausible Community Edition](https://github.com/plausible/community-edition) self-hosts on your own infrastructure. To point this plugin at a self-hosted instance, override `scriptUrl` from the admin form (or from `cms.config.ts` for the initial default):
+
+```ts
+plausiblePlugin({
+  domain: 'example.com',
+  scriptUrl: 'https://analytics.example.com/js/script.js',
+})
+```
+
+To revert to the hosted plausible.io URL, click **Reset to default** in the admin form — that deletes the stored DDB row so the next request falls back to the manifest default.
+
+## Multiple instances
+
+Each `plausiblePlugin(...)` call gets its own `instanceId` namespace, both in the rendered DOM and in the admin settings storage:
+
+```ts
+plugins: [
+  plausiblePlugin({ instanceId: 'marketing', domain: 'marketing.example.com' }),
+  plausiblePlugin({ instanceId: 'product',   domain: 'app.example.com' }),
+]
+```
+
+The admin form lists each instance as its own panel.
+
+## Trust level
+
+`untrusted`. The plugin only contributes a head descriptor that is validated and rendered by `@ampless/runtime`. It does not touch DynamoDB, S3, or any Lambda processor.
+
+## What it does not do
+
+- **CSP nonce propagation** — the script descriptor is emitted without a `nonce`. ampless sites don't enforce a CSP today; once that lands, a dedicated RFP will wire `nonce` end-to-end (middleware → SSR → descriptor).
+- **Plausible custom events** — the loader is injected; custom events fire from your own page code via the standard Plausible `window.plausible(...)` API.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { AmplessPlugin } from 'ampless';
+
+interface PlausibleOptions {
+    /**
+     * The Plausible site domain (e.g. `'example.com'`). Must match the
+     * value registered in the Plausible dashboard exactly — Plausible
+     * uses the string as the row key when ingesting events, so a
+     * mismatch silently drops every pageview.
+     *
+     * Constructor argument seeds the manifest `default`. Empty string
+     * disables the plugin (descriptor returns `[]`) — handy for staging
+     * or for keeping the dependency wired up before the dashboard is
+     * provisioned. New deployments should leave it empty and configure
+     * the value from `/admin/plugins`.
+     */
+    domain?: string;
+    /**
+     * URL of the Plausible script. Defaults to
+     * `https://plausible.io/js/script.js` (the hosted version). Override
+     * for self-hosted Plausible (e.g.
+     * `'https://analytics.example.com/js/script.js'`).
+     *
+     * The manifest field is `required: true` so admins cannot save an
+     * empty value — an empty `src` attribute would silently drop the
+     * loader. To switch back to the hosted plausible.io URL after a
+     * self-hosted override, use "Reset to default" in the admin form.
+     */
+    scriptUrl?: string;
+    /**
+     * Optional namespace for this instance. Defaults to `'plausible'`.
+     * Set distinct values when registering the plugin twice (e.g. one
+     * marketing-site domain + one product-site domain on the same
+     * deployment).
+     */
+    instanceId?: string;
+}
+/**
+ * Factory for the Plausible plugin. Emits a single `<script>`
+ * descriptor with `data-domain` set to the configured domain. The
+ * plugin is `untrusted` — everything runs in the public Next.js
+ * process; no AWS data permissions needed.
+ *
+ * Both settings are read at request time through `ctx.setting()`,
+ * with constructor arguments seeding the manifest defaults.
+ */
+declare function plausiblePlugin(options?: PlausibleOptions): AmplessPlugin;
+
+export { type PlausibleOptions, plausiblePlugin as default };

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+var DEFAULT_SCRIPT_URL = "https://plausible.io/js/script.js";
+function plausiblePlugin(options = {}) {
+  const {
+    domain = "",
+    scriptUrl = DEFAULT_SCRIPT_URL,
+    instanceId = "plausible"
+  } = options;
+  return definePlugin({
+    name: "plausible",
+    instanceId,
+    displayName: { en: "Plausible Analytics", ja: "Plausible Analytics" },
+    apiVersion: 1,
+    trust_level: "untrusted",
+    capabilities: ["publicHead", "adminSettings"],
+    settings: {
+      public: [
+        {
+          type: "text",
+          key: "domain",
+          label: {
+            en: "Site domain",
+            ja: "\u30B5\u30A4\u30C8\u30C9\u30E1\u30A4\u30F3"
+          },
+          description: {
+            en: "The domain registered in Plausible (e.g. example.com). Leave blank to disable the plugin without removing it from cms.config.",
+            ja: "Plausible \u7BA1\u7406\u753B\u9762\u3067\u767B\u9332\u3057\u305F\u30C9\u30E1\u30A4\u30F3 (\u4F8B: example.com)\u3002\u7A7A\u306B\u3059\u308B\u3068 cms.config \u304B\u3089\u524A\u9664\u305B\u305A\u306B\u30D7\u30E9\u30B0\u30A4\u30F3\u3092\u7121\u52B9\u5316\u3067\u304D\u307E\u3059\u3002"
+          },
+          // Accept either empty (disable) or a hostname-like string.
+          // Plausible matches on the exact registered domain, so this
+          // pattern is mostly a "did you paste in a URL by accident"
+          // guard rather than a strict FQDN validator.
+          pattern: "^$|^[a-zA-Z0-9.-]+$",
+          placeholder: "example.com",
+          default: domain
+        },
+        {
+          type: "url",
+          key: "scriptUrl",
+          label: {
+            en: "Script URL",
+            ja: "\u30B9\u30AF\u30EA\u30D7\u30C8 URL"
+          },
+          description: {
+            en: "URL of the Plausible script. Defaults to plausible.io; override for self-hosted Plausible.",
+            ja: "Plausible \u30B9\u30AF\u30EA\u30D7\u30C8\u306E URL\u3002\u30C7\u30D5\u30A9\u30EB\u30C8\u306F plausible.io\u3002self-hosted Plausible \u3092\u4F7F\u3046\u5834\u5408\u306B\u4E0A\u66F8\u304D\u3002"
+          },
+          // required + non-empty default keeps admins from saving
+          // src='' and breaking analytics silently. To switch from a
+          // self-hosted URL back to plausible.io, the admin uses
+          // "Reset to default" (which deletes the DDB row and lets
+          // the resolver fall back to this manifest default).
+          required: true,
+          allowRelative: false,
+          placeholder: DEFAULT_SCRIPT_URL,
+          default: scriptUrl
+        }
+      ]
+    },
+    publicHead(ctx) {
+      const resolvedDomain = (ctx.setting("domain") ?? "").trim();
+      const resolvedScriptUrl = (ctx.setting("scriptUrl") ?? "").trim();
+      if (!resolvedDomain || !resolvedScriptUrl) return [];
+      return [
+        {
+          type: "script",
+          id: `plausible-${instanceId}`,
+          src: resolvedScriptUrl,
+          // `lazyOnload` keeps analytics off the critical hydration
+          // path. The descriptor renderer's `lazyOnload` mapping
+          // adds `defer`; we set `defer: true` explicitly too so the
+          // intent is clear and so a future strategy change doesn't
+          // accidentally drop the defer behaviour.
+          strategy: "lazyOnload",
+          defer: true,
+          attrs: { "data-domain": resolvedDomain }
+        }
+      ];
+    }
+  });
+}
+export {
+  plausiblePlugin as default
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ampless/plugin-plausible",
+  "version": "0.1.1-alpha.0",
+  "description": "Plausible Analytics plugin for ampless",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-plausible"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "1.0.0-alpha.18"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "plausible",
+    "analytics",
+    "privacy"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}