@guckdev/browser 0.8.0 → 0.10.1
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.
- package/README.md +10 -75
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,34 +1,11 @@
|
|
|
1
1
|
# Guck (Browser SDK)
|
|
2
2
|
|
|
3
|
-
Browser SDK for emitting Guck telemetry to
|
|
3
|
+
Browser SDK for emitting Guck telemetry to your dev server at `/guck/emit`.
|
|
4
4
|
This package is intended for **development only** and throws if used in production builds.
|
|
5
5
|
|
|
6
6
|
## Usage
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
```sh
|
|
11
|
-
guck mcp --http-port 7331
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
Create a client and emit events:
|
|
15
|
-
|
|
16
|
-
```ts
|
|
17
|
-
import { createBrowserClient } from "@guckdev/browser";
|
|
18
|
-
|
|
19
|
-
const client = createBrowserClient({
|
|
20
|
-
endpoint: "http://localhost:7331/guck/emit",
|
|
21
|
-
service: "web-ui",
|
|
22
|
-
sessionId: "dev-1",
|
|
23
|
-
});
|
|
24
|
-
|
|
25
|
-
await client.emit({ message: "hello from the browser" });
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## Vite drop-in (dev)
|
|
29
|
-
|
|
30
|
-
1) `pnpm add -D @guckdev/vite`
|
|
31
|
-
2) Add the plugin in `vite.config.ts`:
|
|
8
|
+
1) Add the Vite plugin:
|
|
32
9
|
|
|
33
10
|
```ts
|
|
34
11
|
import { defineConfig } from "vite";
|
|
@@ -39,40 +16,18 @@ export default defineConfig({
|
|
|
39
16
|
});
|
|
40
17
|
```
|
|
41
18
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
The browser will POST to your Vite dev server (for example `http://localhost:5173/guck/emit`).
|
|
45
|
-
The plugin forwards those requests to the shared MCP ingest at `http://127.0.0.1:7331/guck/emit`.
|
|
46
|
-
|
|
47
|
-
## Quick local setup (HTTPS dev host, no Vite plugin)
|
|
48
|
-
|
|
49
|
-
1) Start the MCP server with HTTP ingest:
|
|
50
|
-
|
|
51
|
-
```sh
|
|
52
|
-
guck mcp --http-port 7331
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
2) If your app runs on HTTPS (e.g. `https://local.dev`), proxy the ingest
|
|
56
|
-
endpoint through Caddy so the browser stays on HTTPS:
|
|
57
|
-
|
|
58
|
-
```caddyfile
|
|
59
|
-
:443 {
|
|
60
|
-
# your existing site config...
|
|
61
|
-
|
|
62
|
-
handle_path /guck/emit {
|
|
63
|
-
reverse_proxy 127.0.0.1:7331
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
3) Use the proxied endpoint:
|
|
19
|
+
2) Create a client and emit events:
|
|
69
20
|
|
|
70
21
|
```ts
|
|
22
|
+
import { createBrowserClient } from "@guckdev/browser";
|
|
23
|
+
|
|
71
24
|
const client = createBrowserClient({
|
|
72
|
-
endpoint: "
|
|
73
|
-
service: "
|
|
25
|
+
endpoint: "/guck/emit",
|
|
26
|
+
service: "web-ui",
|
|
74
27
|
sessionId: "dev-1",
|
|
75
28
|
});
|
|
29
|
+
|
|
30
|
+
await client.emit({ message: "hello from the browser" });
|
|
76
31
|
```
|
|
77
32
|
|
|
78
33
|
## Keep it out of production
|
|
@@ -83,7 +38,7 @@ Use a development-only import so the SDK never gets bundled for production:
|
|
|
83
38
|
if (import.meta.env.DEV) {
|
|
84
39
|
const { createBrowserClient } = await import("@guckdev/browser");
|
|
85
40
|
const client = createBrowserClient({
|
|
86
|
-
endpoint: "
|
|
41
|
+
endpoint: "/guck/emit",
|
|
87
42
|
service: "playground",
|
|
88
43
|
sessionId: "dev-1",
|
|
89
44
|
});
|
|
@@ -103,28 +58,8 @@ stop();
|
|
|
103
58
|
```
|
|
104
59
|
|
|
105
60
|
Notes:
|
|
106
|
-
- The HTTP ingest endpoint is CORS-enabled by default.
|
|
107
|
-
- If your page is served over HTTPS, posting to an HTTP localhost endpoint may be blocked by mixed-content rules.
|
|
108
61
|
- The SDK only runs when the endpoint host is local (`localhost`, `127.0.0.1`, `local.*`, `*.local`).
|
|
109
|
-
- `createBrowserClient()` throws when `NODE_ENV` / `import.meta.env.PROD` indicates production.
|
|
110
62
|
- `installAutoCapture()` should usually be called once at app startup; repeated calls will wrap console multiple times.
|
|
111
63
|
- If you install it inside a component or test, call `stop()` on cleanup to avoid duplicate logging.
|
|
112
64
|
- For SPAs, it's fine to call `installAutoCapture()` once in your app entry (e.g. `index.ts`) and never call `stop()`.
|
|
113
65
|
- There is no prebuilt UMD/IIFE bundle yet; for vanilla JS you should use a bundler (Vite/Rollup/etc) or a native ESM import in a modern build.
|
|
114
|
-
|
|
115
|
-
### Caddy (HTTPS dev) proxy example
|
|
116
|
-
|
|
117
|
-
If your frontend runs behind Caddy on HTTPS, proxy a path to the local ingest server
|
|
118
|
-
so the browser stays on HTTPS:
|
|
119
|
-
|
|
120
|
-
```caddyfile
|
|
121
|
-
:443 {
|
|
122
|
-
# your existing site config...
|
|
123
|
-
|
|
124
|
-
handle_path /guck/emit {
|
|
125
|
-
reverse_proxy 127.0.0.1:7331
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Then point the client at `https://your-dev-host/guck/emit`.
|