@auspex-ai/next 1.4.1 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +42 -34
  2. package/package.json +11 -2
package/README.md CHANGED
@@ -1,50 +1,58 @@
1
1
  # @auspex-ai/next
2
2
 
3
- Next.js アダプタ。ブラウザの計装(`@auspex-ai/core`)の Provider と、ビルド時にアイコン名・要素の参照を DOM へ書き込む `withAuspex`。
3
+ Auspex instrumentation for Next.js apps (version 14 or later, app router and pages router).
4
4
 
5
- ## withAuspex
5
+ ## Install
6
6
 
7
- ```ts
8
- // next.config.ts
9
- import { withAuspex } from '@auspex-ai/next/config';
10
-
11
- export default withAuspex(nextConfig, { host: 'https://<受信口のドメイン>' });
7
+ ```sh
8
+ pnpm add @auspex-ai/core @auspex-ai/next
9
+ # or: npm install @auspex-ai/core @auspex-ai/next
10
+ # or: yarn add @auspex-ai/core @auspex-ai/next
12
11
  ```
13
12
 
14
- - **できるだけ最も外側に置く。** `webpack` / `turbopack` のキーを落とすプラグインが外側にあると、ローダーが失われる。
15
- - 戻り値の型は入力に合わせる(オブジェクトならオブジェクト、関数なら async の関数)。二重に掛けても 1 回分になる。
16
-
17
- ### 要素の参照(Design Doc #50)
13
+ ## Usage
14
+
15
+ Add one `AuspexProvider` to `app/layout.tsx` (app router) or `pages/_app.tsx` (pages router):
16
+
17
+ ```tsx
18
+ import { AuspexProvider } from '@auspex-ai/next';
19
+
20
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
21
+ return (
22
+ <html lang="en">
23
+ <body>
24
+ <AuspexProvider
25
+ publicKey={process.env.NEXT_PUBLIC_AUSPEX_KEY}
26
+ host={process.env.NEXT_PUBLIC_AUSPEX_HOST ?? ''}
27
+ >
28
+ {children}
29
+ </AuspexProvider>
30
+ </body>
31
+ </html>
32
+ );
33
+ }
34
+ ```
18
35
 
19
- クリックされうる要素には、名前(ハンドラ名・パスなど)そのものではなく、名前の鍵付きハッシュ(`data-auspex-ref`)だけを書く。名前はビルドの終わりに Auspex へ登録し、受信口が参照から名前に引き直す。
36
+ Wrap `next.config` with `withAuspex` so that Auspex can name buttons and other elements. Set your build key in the `AUSPEX_BUILD_KEY` environment variable of the build, and don't add the `NEXT_PUBLIC_` prefix to it.
20
37
 
21
- 1. アプリの設定のページで**ビルド鍵**(`auspex_bk_...`)を発行する(発行時に 1 回だけ表示される)。
22
- 2. ビルドの環境変数 `AUSPEX_BUILD_KEY` に置く。**CI の秘密に置き、`NEXT_PUBLIC_` を付けない**(付けるとバンドルに入り、鍵で参照を作れてしまう)。
23
- 3. 登録の受け口 `host`(受信口と同じドメイン。https)を `withAuspex(cfg, { host })` か環境変数 `NEXT_PUBLIC_AUSPEX_HOST` で渡す。ビルド鍵を送るので https のみ(開発用の `http://localhost`・`http://127.0.0.1` は除く)。
24
- 4. セルフホスト版で IAP の背後に置いた internal へ登録するときだけ、ビルドの環境変数を足す: `AUSPEX_INTERNAL_HOST`(internal の https の URL。あれば登録だけそちらへ送る。`host` が無くてもよい)と `AUSPEX_IAP_SERVICE_ACCOUNT`(IAP を通すサービスアカウントのメール。CI に Google の認証情報、プロジェクトに `google-auth-library` が要る。任意の peer 依存)。
38
+ ```js
39
+ // next.config.mjs
40
+ import { withAuspex } from '@auspex-ai/next/config';
25
41
 
26
- 鍵か `host` が無い、`elementNames: false`、`next dev` のときは参照を書かない(手書きの `data-auspex-name` / `data-auspex-ref` を消すだけ)。本番のビルドで理由が分かる場合は警告を出す。
42
+ const nextConfig = {};
27
43
 
28
- ### 登録の経路
44
+ export default withAuspex(nextConfig);
45
+ ```
29
46
 
30
- - 既定は Next の `compiler.runAfterProductionCompile`(本番のビルドの終わりに呼ばれる。Next 15.4.1 以上の安定版の webpack、16 以上)。既にある hook は先に呼ぶ。登録に失敗してもビルドは落とさず警告する。
31
- - hook が使えない Next(15.4.1 未満、版が判定できない、15.x の Turbopack)では `registerNames: 'cli'` を渡し、`next build` の後に CLI を流す:
47
+ For the write key, the build key, and all options, see the [quickstart](https://docs.auspex.blue/getting-started/quickstart/) and the [instrumentation reference](https://docs.auspex.blue/reference/instrumentation/).
32
48
 
33
- ```ts
34
- export default withAuspex(nextConfig, { registerNames: 'cli' });
35
- ```
49
+ ## Documentation
36
50
 
37
- ```sh
38
- next build && AUSPEX_BUILD_KEY=... auspex-register-names --host https://<受信口のドメイン>
39
- ```
51
+ See the [Auspex documentation](https://docs.auspex.blue).
40
52
 
41
- CLI のオプション: `--host`(既定は `NEXT_PUBLIC_AUSPEX_HOST`。環境変数 `AUSPEX_INTERNAL_HOST` があればそちらを優先)、`--dist-dir`(既定 `.next`)、`--build-id`(既定は `<distDir>/BUILD_ID`。無い・128 文字超は自前の id)。登録の失敗では終了コード 0 のまま警告する。
53
+ - [Quickstart](https://docs.auspex.blue/getting-started/quickstart/)
54
+ - [Instrumentation reference](https://docs.auspex.blue/reference/instrumentation/)
42
55
 
43
- ### オプション
56
+ ## License
44
57
 
45
- | オプション | 既定 | 内容 |
46
- | --- | --- | --- |
47
- | `iconNames` | `true` | `false` でアイコン名の参照(`data-auspex-icon-ref`)を書かない。参照は要素名と同じビルド鍵で計算し、名前は同じ登録(`icons`)でビルドの終わりに Auspex へ送る。鍵が無い・strip のときは何も書かない(手書きの `data-auspex-icon` は消える)。ライブラリの class から取る名前は今のまま |
48
- | `elementNames` | `true` | `false` で要素の参照を書かない |
49
- | `registerNames` | なし | `'cli'` で hook ではなく CLI で登録する |
50
- | `host` | `NEXT_PUBLIC_AUSPEX_HOST` | 登録の受け口 |
58
+ Apache-2.0
package/package.json CHANGED
@@ -1,9 +1,18 @@
1
1
  {
2
2
  "name": "@auspex-ai/next",
3
- "version": "1.4.1",
3
+ "version": "1.4.2",
4
+ "description": "Auspex instrumentation for Next.js apps",
4
5
  "type": "module",
5
6
  "sideEffects": false,
6
7
  "license": "Apache-2.0",
8
+ "homepage": "https://docs.auspex.blue/",
9
+ "keywords": [
10
+ "auspex",
11
+ "nextjs",
12
+ "next",
13
+ "instrumentation",
14
+ "analytics"
15
+ ],
7
16
  "repository": {
8
17
  "type": "git",
9
18
  "url": "git+https://github.com/NA-LUDENS/auspex.git",
@@ -34,7 +43,7 @@
34
43
  "module": "./dist/index.mjs",
35
44
  "types": "./dist/index.d.mts",
36
45
  "dependencies": {
37
- "@auspex-ai/core": "^1.4.1",
46
+ "@auspex-ai/core": "^1.4.2",
38
47
  "@babel/parser": "^7.29.8",
39
48
  "magic-string": "^1.4.1"
40
49
  },