fimo 2.8.0-staging.4 → 2.8.0-staging.5
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/assets/skills/fimo-cli/references/analytics.md +5 -11
- package/assets/skills/fimo-cli/references/update.md +6 -9
- package/assets/skills/fimo-code/SKILL.md +1 -5
- package/assets/skills/fimo-code/references/analytics.md +47 -81
- package/assets/skills/fimo-code/references/frameworks/vite-react.md +1 -1
- package/assets/skills/fimo-studio/references/ai-chat.md +6 -2
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +3 -3
- package/package.json +9 -9
- package/templates/astro/package.json +3 -2
- package/templates/astro/src/layouts/Base.astro +2 -0
- package/templates/nextjs/package.json +4 -3
- package/templates/nextjs/src/app/layout.tsx +2 -0
- package/templates/react-router/package.json +5 -4
- package/templates/react-router/src/root.tsx +2 -0
- package/templates/sveltekit/package.json +3 -2
- package/templates/sveltekit/src/routes/+layout.svelte +2 -0
- package/templates/vite/package.json +5 -4
- package/templates/vite/src/LocaleLayout.tsx +2 -0
|
@@ -1,16 +1,10 @@
|
|
|
1
1
|
# Analytics workflow
|
|
2
2
|
|
|
3
|
-
Pageview aggregates are read for the selected branch.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
If counts are zero, check the selected branch, built scripts, enabled setting,
|
|
9
|
-
browser requests and stored results before diagnosing a missing implementation.
|
|
10
|
-
A successful HTTP response alone does not establish that a row was stored.
|
|
11
|
-
Use `fimo-code` analytics setup for the standalone `fimo-analytics` APIs.
|
|
12
|
-
Confirm that the selected package release contains them before generating imports;
|
|
13
|
-
older Fimo releases and existing published sites do not acquire a tracker automatically.
|
|
3
|
+
Pageview aggregates are read for the selected branch. Reading analytics does not
|
|
4
|
+
install tracking. For installation or missing pageview requests, load
|
|
5
|
+
`fimo skills get fimo-code --ref analytics`. For zero counts, first check the
|
|
6
|
+
branch, date range and device filter using the guidance below. A successful HTTP
|
|
7
|
+
response alone does not establish that a row was stored.
|
|
14
8
|
|
|
15
9
|
Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
|
|
16
10
|
|
|
@@ -24,15 +24,12 @@ What it refuses to touch:
|
|
|
24
24
|
|
|
25
25
|
## Analytics when updating
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
existing tracker before adding one. After the developer publishes the update,
|
|
34
|
-
verify new pageviews in Studio. Existing analytics history remains available.
|
|
35
|
-
The update command itself does not publish the website.
|
|
27
|
+
If the project declares `fimo-analytics`, the update keeps it aligned with the
|
|
28
|
+
other Fimo packages. The update never adds a tracker: React Router projects that
|
|
29
|
+
tracked through `FimoProviders` before 2.8.0 need `<Analytics />`, and other
|
|
30
|
+
projects without `fimo-analytics` should add it to match new projects. For setup and
|
|
31
|
+
verification, load `fimo skills get fimo-code --ref analytics`. The update
|
|
32
|
+
command itself does not publish the website.
|
|
36
33
|
|
|
37
34
|
## Reading the report
|
|
38
35
|
|
|
@@ -78,11 +78,7 @@ Each reference defines one package contract. Fetch it when the task reaches that
|
|
|
78
78
|
|
|
79
79
|
## Analytics
|
|
80
80
|
|
|
81
|
-
For pageview installation, read [references/analytics.md](references/analytics.md).
|
|
82
|
-
`FimoProviders` from `fimo-react-router` already tracks when `VITE_API_URL` and
|
|
83
|
-
`VITE_ENABLE_ANALYTICS=true` are configured. Inspect the installed version and
|
|
84
|
-
browser requests before adding a sender. Hosting or the neutral Vite plugin alone
|
|
85
|
-
does not install a tracker. Older releases do not acquire new package exports.
|
|
81
|
+
For pageview installation or debugging, read [references/analytics.md](references/analytics.md).
|
|
86
82
|
|
|
87
83
|
## Non-negotiable boundaries
|
|
88
84
|
|
|
@@ -1,104 +1,70 @@
|
|
|
1
1
|
# Pageview tracking
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`FimoProviders` already tracks when `VITE_API_URL` and
|
|
5
|
-
`VITE_ENABLE_ANALYTICS=true` are present. Do not mount another sender beside an
|
|
6
|
-
unmodified legacy tracker. The neutral Vite plugin and hosting alone do not
|
|
7
|
-
install tracking.
|
|
3
|
+
## Before adding tracking
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
Inspect the installed packages and the built page first; never mount a second
|
|
6
|
+
sender beside one the app already renders. Projects created from current
|
|
7
|
+
templates already declare `fimo-analytics` and mount `<Analytics />` in the root. `fimo-react-router` before 2.8.0
|
|
8
|
+
tracked from `FimoProviders`; from 2.8.0 it does not.
|
|
10
9
|
|
|
11
|
-
Install
|
|
12
|
-
|
|
13
|
-
release does not imply these standalone APIs exist, and existing published
|
|
14
|
-
sites need a code update to gain missing instrumentation.
|
|
10
|
+
Install `fimo-analytics`, preserving the project's chosen version or channel.
|
|
11
|
+
Publish the code change before verifying live traffic.
|
|
15
12
|
|
|
16
13
|
```sh
|
|
17
14
|
pnpm add fimo-analytics
|
|
18
15
|
```
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
| SvelteKit | default `Analytics` from `fimo-analytics/sveltekit` | Root `+layout.svelte` |
|
|
34
|
-
| Vue | `{ Analytics }` from `fimo-analytics/vue` | Root component, history routing |
|
|
35
|
-
| Nuxt | `modules: ['fimo-analytics/nuxt']` | `analytics: { endpoint, enabled }` in config |
|
|
36
|
-
|
|
37
|
-
Components accept `endpoint` and `enabled`. React example:
|
|
17
|
+
## Install and mount
|
|
18
|
+
|
|
19
|
+
Mount the matching component once, with no props:
|
|
20
|
+
|
|
21
|
+
| Framework | Import | Placement |
|
|
22
|
+
| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
23
|
+
| React Router | `{ Analytics }` from `fimo-analytics/react-router` | Root route component beside `<Outlet />`, or inside the existing `<BrowserRouter>` / `<HashRouter>` |
|
|
24
|
+
| Next.js | `{ Analytics }` from `fimo-analytics/next` | App Router: inside `<body>` in `app/layout.tsx`. Pages Router: beside `<Component {...pageProps} />` in `pages/_app.tsx` |
|
|
25
|
+
| Astro | default `Analytics` from `fimo-analytics/astro` | Shared layout, no `client:*` directive |
|
|
26
|
+
| SvelteKit | default `Analytics` from `fimo-analytics/sveltekit` | Root `src/routes/+layout.svelte` |
|
|
27
|
+
| React (Vite) | `{ Analytics }` from `fimo-analytics/react` | Application root |
|
|
28
|
+
| Svelte | default `Analytics` from `fimo-analytics/svelte` | Root component |
|
|
29
|
+
| Vue | `{ Analytics }` from `fimo-analytics/vue` | Root component |
|
|
38
30
|
|
|
39
31
|
```tsx
|
|
40
32
|
import { Analytics } from 'fimo-analytics/next';
|
|
41
|
-
<Analytics
|
|
33
|
+
<Analytics />;
|
|
42
34
|
```
|
|
43
35
|
|
|
44
|
-
For Nuxt,
|
|
45
|
-
|
|
46
|
-
navigation; Nuxt covers reused pages and query changes. Generic React, Vue and
|
|
47
|
-
Svelte observe history. For a router that changes the URL before committing,
|
|
48
|
-
use the manual core. For Vue Router, initialize in `onMounted` after initial
|
|
49
|
-
router readiness, send once, subscribe to `router.afterEach`, send only when
|
|
50
|
-
`failure` is falsy, and remove the subscription and destroy on unmount.
|
|
51
|
-
|
|
52
|
-
```ts
|
|
53
|
-
import { init } from 'fimo-analytics';
|
|
54
|
-
const analytics = init({ endpoint, enabled: isProduction, routing: 'manual' });
|
|
55
|
-
// In the router's successful-navigation callback:
|
|
56
|
-
analytics.pageview();
|
|
57
|
-
// During cleanup:
|
|
58
|
-
analytics.destroy();
|
|
59
|
-
```
|
|
36
|
+
For Nuxt, mount nothing: add `'fimo-analytics/nuxt'` to `modules` in
|
|
37
|
+
`nuxt.config.ts` and run `pnpm add -D @nuxt/kit`.
|
|
60
38
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
the React Router adapter already reads its router's virtual location.
|
|
39
|
+
The generic React, Svelte and Vue components observe browser history and do not
|
|
40
|
+
resolve hash-router paths; use a framework adapter when one exists.
|
|
64
41
|
|
|
65
|
-
For plain HTML, copy
|
|
42
|
+
For a plain HTML Vite site, copy `node_modules/fimo-analytics/dist/browser.js`
|
|
43
|
+
to `public/fimo-analytics.js` and add this classic script to `index.html`:
|
|
66
44
|
|
|
67
45
|
```html
|
|
68
|
-
<script
|
|
46
|
+
<script
|
|
47
|
+
defer
|
|
48
|
+
src="/fimo-analytics.js"
|
|
49
|
+
data-endpoint="%VITE_API_URL%/e/p"
|
|
50
|
+
data-enabled="%VITE_ENABLE_ANALYTICS%"
|
|
51
|
+
></script>
|
|
69
52
|
```
|
|
70
53
|
|
|
71
|
-
|
|
72
|
-
builds. No framework peer is required for core or HTML. Framework peers are
|
|
73
|
-
optional and only the chosen adapter's framework is needed.
|
|
74
|
-
|
|
75
|
-
## Choose the enabled guard
|
|
76
|
-
|
|
77
|
-
Tracking defaults to enabled, so always pass `enabled`. Never use `NODE_ENV`:
|
|
78
|
-
a Fimo hosted preview is a production build, so that guard leaves previews
|
|
79
|
-
reporting. Read the build variable Fimo already sets:
|
|
80
|
-
|
|
81
|
-
| Framework | Guard |
|
|
82
|
-
| ------------------------- | -------------------------------------------------- |
|
|
83
|
-
| React Router and any Vite | `import.meta.env.VITE_ENABLE_ANALYTICS === 'true'` |
|
|
84
|
-
| Next.js | `process.env.NEXT_PUBLIC_FIMO_ENV === 'prod'` |
|
|
85
|
-
| Build-time server env | `process.env.FIMO_ENV === 'prod'` |
|
|
86
|
-
|
|
87
|
-
Astro, SvelteKit, Svelte and Vue have no browser-visible environment name from
|
|
88
|
-
Fimo. Read `FIMO_ENV` at build time and pass the boolean into the bundle through
|
|
89
|
-
the framework's own public-variable mechanism. Do not invent a `PUBLIC_FIMO_ENV`
|
|
90
|
-
and do not expose the whole environment name when a boolean is enough.
|
|
54
|
+
## Hosting controls tracking
|
|
91
55
|
|
|
92
|
-
|
|
56
|
+
Fimo hosting provides the destination and the switch while the site builds:
|
|
57
|
+
on for published sites, off for previews. Without it, as in local development,
|
|
58
|
+
tracking is off; `[fimo-analytics]` in the browser console, or in build logs for
|
|
59
|
+
Astro and Nuxt, says why. Do not add an `endpoint`, an `enabled` guard, or a
|
|
60
|
+
`NODE_ENV` check.
|
|
93
61
|
|
|
94
|
-
|
|
95
|
-
`bl_preview_token` also suppresses sends. SSR and disabled calls are inert.
|
|
96
|
-
Do not add browser secrets, project IDs or branch claims to payloads.
|
|
62
|
+
## Verify and diagnose
|
|
97
63
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
64
|
+
On the published site, check Network for one POST to `/e/p` on the initial load
|
|
65
|
+
and on each pathname or query change, including back/forward and revisits.
|
|
66
|
+
Hash-only changes do not send. Previews send nothing. If requests are missing,
|
|
67
|
+
check that the deployed app mounts the component and read the `[fimo-analytics]`
|
|
68
|
+
diagnostics. If requests arrive but counts stay at zero, use the `fimo-cli`
|
|
69
|
+
analytics reference to check the branch, date range and device filter; headless
|
|
70
|
+
browsers count as bots. A 202 response does not prove a stored row.
|
|
@@ -27,7 +27,7 @@ Import it from `fimo-react-router/vite` whenever the application renders through
|
|
|
27
27
|
|
|
28
28
|
## Application root
|
|
29
29
|
|
|
30
|
-
`FimoProviders` needs a React Router context for Studio navigation
|
|
30
|
+
`FimoProviders` needs a React Router context for Studio navigation. Keep the application's existing router type. For pageview tracking, read `references/analytics.md`.
|
|
31
31
|
|
|
32
32
|
```tsx
|
|
33
33
|
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
## Where to Find It
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Open the **Chats** tab in the project header. On a phone, the Chat tab at the bottom opens the chat list first; select a chat to open it.
|
|
4
|
+
|
|
5
|
+
## Working in Several Chats
|
|
6
|
+
|
|
7
|
+
Chat has its own **Chats** tab in the project header; the tab shows how many chats have unread activity. A project can have several chats, shared by everyone on the project. The left list shows them most recently active first with a status (**Working** with a spinner while replying, **Done** once the reply finished) and their last words; a dot marks unread activity. Select **+** for a new chat (its name comes from the first message; an empty chat offers starter requests), the search icon to find a chat, the filter icon to show only Working or Done chats, and the list settings for ordering and showing read, unread, or archived chats. The buttons above an open chat (or a right-click on a row) mark it unread, pin, archive, or mute it, for you only; the settings icon opens the chat's settings, which rename it for everyone, hold the same pin, mute and archive switches, and delete it, stopping a running reply first. Each chat has only its own messages and context. The open chat is in the page address (`/chats?chat=<id>`), so a link or reload opens the same chat.
|
|
4
8
|
|
|
5
9
|
## Sending a Message
|
|
6
10
|
|
|
@@ -51,7 +55,7 @@ Delete a proposal from the Branch picker when you no longer need it. Pull is una
|
|
|
51
55
|
|
|
52
56
|
Chat changes are prepared separately and then applied to the environment you are viewing. Most changes merge automatically.
|
|
53
57
|
|
|
54
|
-
If the project changed in the same place while the AI was working, the response shows a **Review changes** card and an attention banner above the chat input.
|
|
58
|
+
If the project changed in the same place while the AI was working, the response shows a **Review changes** card and an attention banner above the chat input.
|
|
55
59
|
|
|
56
60
|
Choose **Auto fix** or keep chatting to let Fimo continue in the retained proposal, resolve the conflict, and retry the merge. Choose **Review manually** to inspect and resolve the proposal yourself. Discarding leaves the current environment unchanged and permanently removes the proposal.
|
|
57
61
|
|