@intlayer/docs 9.0.0-canary.8 → 9.0.0

package/docs/en/migration_from_vue-i18n_to_intlayer.md

@@ -100,19 +100,23 @@ The following steps are the minimum required to get your existing `vue-i18n` app
 Install the Intlayer core packages and the compat adapter:
 
 ```bash packageManager="npm"
-npx intlayer-cli init --interactive
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer-cli init --interactive
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer-cli init --interactive
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
 ```
 
 ```bash packageManager="bun"
-bunx intlayer-cli init --interactive
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/docs/en/releases/v9.md

@@ -1,27 +1,45 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-26
+updatedAt: 2026-07-08
 title: New Intlayer v9 - What's new?
-description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries, support for Collections and Variants, self-hosting via Docker Compose, and the new @intlayer/analytics package for content A/B testing.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
+  - CMS SDK
+  - Self-Hosting
+  - Docker
+  - Analytics
+  - A/B Testing
   - i18next
   - next-intl
   - vue-i18n
+youtubeVideo: https://www.youtube.com/watch?v=ia6JmVf-kkU
 slugs:
   - doc
   - releases
   - v9
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Add @intlayer/analytics: page/locale + content-exposure tracking, A/B testing, and the dashboard Analytics page"
 author: aymericzip
 ---
 
 # New Intlayer v9 - What's new?
 
-Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections** and **Variants**.
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.), adds support for rich content structures (**Collections** and **Variants**), and introduces **`@intlayer/analytics`** to track content exposure and run A/B tests.
+
+<iframe
+  src="https://www.youtube.com/embed/ia6JmVf-kkU"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo Video - New Intlayer v9 - What's new?"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
 
 ## Table of contents
 
@@ -107,30 +125,42 @@ Intlayer v9 expands beyond static key-value objects, allowing dictionaries to de
 
 ### 1. Collections
 
-Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists):
+Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists). Each item lives in its own `.content.ts` file with the same `key` and an `item` number:
+
+```ts fileName="faq.1.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
 
-```ts fileName="faq.content.ts"
+```ts fileName="faq.2.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "faq",
-  content: [
-    {
-      question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
-      answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
-    },
-  ],
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
 } satisfies Dictionary;
 ```
 
 #### Usage:
 
 ```ts
-// Fetch all items
+// Fetch all items as an array
 const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
 
-// Fetch single item by index
-const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
 ```
 
 ### 2. Variants
@@ -178,30 +208,54 @@ export default {
 #### Usage:
 
 ```ts
-// Fetches only the requested item dynamically (requires Suspense)
+// Fetches only the requested record dynamically (requires Suspense)
 const product = useIntlayer("product-copy", {
-  id: "prod_123",
-  category: "books",
+  variant: { id: "prod_123", category: "books" },
 });
 ```
 
 ---
 
-## Dynamic Loading & Bundle Size Optimizations
-
-To keep bundles extremely small, Intlayer v9 supports dynamic lazy loading.
-
-In your configuration, set `importMode` to `'dynamic'` or `'fetch'`:
-
-```ts fileName="intlayer.config.ts"
-export default {
-  dictionary: {
-    importMode: "dynamic", // "static" | "dynamic" | "fetch"
-  },
+## `@intlayer/analytics`: content exposure tracking & A/B testing
+
+A new optional package, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md), tells you which content is actually shown to your visitors — and closes the loop on **Collections & Variants** by letting you A/B test content and measure conversions per variant.
+
+- **Provider-level tracking**: `IntlayerProvider` (React / Next.js / React Native) automatically records `page_view` events on load, route change, and locale change.
+- **Node-level tracking**: every `useIntlayer` resolution reports a `content_exposure` event — which dictionary key, key path, locale, and (when applicable) A/B **variant** was displayed. Repeated exposures within a flush window are coalesced.
+- **Deterministic A/B assignment**: `getVariant(experimentKey, variants)` assigns each session to a variant with **no server round-trip**, so there is no flicker before first render.
+- **`useConversion()`**: attribute a goal (signup, click, purchase…) to the variant a session was exposed to.
+- **Zero cost when not installed**: same tree-shakeable pattern as `@intlayer/editor` — dynamic `import()` wrapped in `try/catch`, plus a compile-time env var (`INTLAYER_ANALYTICS_ENABLED`) that dead-code-eliminates the whole integration for apps that don't opt in.
+- **No new config schema**: reuses `editor.backendURL` (ingestion endpoint / self-hosting) and `editor.clientId` (project key, also the enable switch).
+- **Privacy-respecting**: anonymous session hashing (SHA-256, no raw ids stored), no IP storage, coarse country-only geolocation, batched requests roughly every 20 seconds.
+- **Dashboard**: a new **Analytics** page (shown in the sidebar once a project is selected) reports active users, users today, users over the last 7/30/90 days, a visitor evolution graph, and Locales vs. Location breakdowns.
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
 };
 ```
 
-At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace `useIntlayer` / `getIntlayer` calls with tree-shakeable wrappers (`useDictionary` / `useDictionaryDynamic`). Only the content required for the selected collection item, variant, or locale is loaded, preventing your production bundle from containing unused translations.
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+Available today for React, Next.js, and React Native (via `react-intlayer`); other framework bindings (Vue, Svelte, Angular, …) are planned, following the same rollout pattern as `@intlayer/editor`. See the [Analytics documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) for the full guide.
 
 ---
 
@@ -284,6 +338,44 @@ npm install intlayer react-native-intlayer
 
 ---
 
+## CMS SDK: use Intlayer as a headless content database
+
+Intlayer v9 ships a clean, auto-authenticating SDK in `@intlayer/api` to interact with the CMS programmatically — fetch projects, fetch dictionaries, and push or update them from your own server, scripts, or CI. Authentication (OAuth2 `client_credentials`) is handled and refreshed for you.
+
+The SDK is split into **two separate imports** so your bundle includes only the domains you actually use:
+
+1. `createIntlayerCMS` — a lightweight **authenticator** holding the credentials and the managed token (no domain client bundled).
+2. `dictionaryEndpoint`, `projectEndpoint`, … — per-domain **endpoint binders**, each imported from its own subpath.
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS();
+
+// Read
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// Write — use the CMS like a database
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> Security: the CMS credentials grant write access to your content. Only ever create the authenticator on the **server side** — never ship `clientId` / `clientSecret` to the browser.
+
+---
+
+## Self-Hosting
+
+Intlayer v9 ships first-class support for running your own Intlayer instance with a single command. No Intlayer Cloud account required.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+The installer downloads a `docker-compose.yml` and a `.env`, auto-generates the required secrets, and runs `docker compose up -d`. Everything — the dashboard, the API, the database, object storage, and transactional email — runs locally in containers.
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
@@ -300,5 +392,8 @@ If you are upgrading from v8, note that the v9 does not include breaking changes
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
 - [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Analytics - Content exposure tracking & A/B testing](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
 - [React Native & Expo Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native+expo.md)
+- [CMS SDK - Programmatic access with @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md)

package/docs/en/self_hosting.md

@@ -0,0 +1,310 @@
+---
+createdAt: 2026-06-30
+updatedAt: 2026-07-02
+title: Self-Hosting Intlayer
+description: Run a complete Intlayer instance on your own infrastructure with a single container. No Intlayer Cloud account required.
+keywords:
+  - Self-Hosting
+  - Docker
+  - Intlayer
+  - CMS
+  - Installation
+  - Infrastructure
+slugs:
+  - doc
+  - self-hosting
+author: aymericzip
+---
+
+# Self-Hosting Intlayer
+
+Intlayer can run on your own infrastructure. No Intlayer Cloud account required. A single all-in-one Docker image bundles the dashboard, the API, and the local datastores (Redis and MinIO) it needs, supervised by [s6-overlay](https://github.com/just-containers/s6-overlay).
+
+The only external dependency is **MongoDB**: the backend connects to a MongoDB **Atlas** cluster, which you provide. Everything else runs inside the container.
+
+## Table of Contents
+
+<TOC/>
+
+---
+
+## Architecture
+
+```
+                ┌─────────────────────────────┐
+ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
+ (localhost)    └─────────────────────────────┘   │ VITE_BACKEND_URL (baked at build)
+                ┌─────────────────────────────┐   │
+                │  backend (Fastify/Bun)  :3100│ ◀─┘
+                └──────────────┬──────────────┘
+          ┌──────────┬─────────┼───────────────────────┐
+          ▼          ▼         ▼                        ▼
+       redis:6379  minio:9000  Chromium            MongoDB Atlas
+       (bundled)   (S3 API)    (in-image)          (external, via DB_*)
+                   minio:9001
+                   (console)
+```
+
+Chromium (used for Puppeteer screenshot generation) is bundled inside the image. No separate container is needed. Redis and MinIO run inside the container. MongoDB is **not** hosted by the image; the backend connects to your Atlas cluster over `mongodb+srv://`.
+
+---
+
+## Prerequisites
+
+- **Docker** ≥ 24.
+- Ports `3000`, `3100`, `9000`, and `9001` available on the host.
+- A Linux or macOS host (or WSL2 on Windows).
+- A **MongoDB Atlas** cluster (a free tier works). Create one at [mongodb.com/atlas](https://www.mongodb.com/atlas).
+- A **Resend** API key for transactional email. Get one at [resend.com](https://resend.com).
+
+---
+
+## Quick start
+
+Pull and run the published image, supplying your MongoDB Atlas credentials and secrets:
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+Then open **http://localhost:3000**.
+
+> The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
+
+---
+
+## First-run setup
+
+On a fresh instance (empty database), opening the dashboard redirects you to the **`/init`** page:
+
+1. Create the first account. Because the users collection is empty, this account is automatically promoted to **super admin**.
+2. A verification email is sent (via Resend). Email verification is **mandatory** — this is why `RESEND_API_KEY` must be set before you start.
+3. Click the link in the email, then sign in.
+
+Once an admin exists, `/init` redirects to the standard sign-in page.
+
+---
+
+## Services
+
+| Service     | Location           | Host port(s)                  | Purpose                                                       |
+| ----------- | ------------------ | ----------------------------- | ------------------------------------------------------------- |
+| **app**     | bundled            | `3000`                        | TanStack Start dashboard (CMS UI)                             |
+| **backend** | bundled            | `3100`                        | Fastify REST API (`/health` endpoint)                         |
+| **redis**   | bundled            | internal                      | Job queues (BullMQ) and caching (ioredis)                     |
+| **minio**   | bundled            | `9000` (S3), `9001` (console) | S3-compatible object storage for avatars and screenshots      |
+| **mongo**   | **external** (you) | —                             | MongoDB Atlas, provided via `DB_ID` / `DB_MDP` / `DB_CLUSTER` |
+
+> MinIO port `9000` must be reachable by the browser because uploaded assets (avatars, screenshots) are loaded directly from `S3_PUBLIC_URL=http://localhost:9000/intlayer`.
+
+---
+
+## Environment variables
+
+### Required
+
+| Variable               | Example                      | Description                                                                                                                                  |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas user                                                                                                                           |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas password                                                                                                                       |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host (used in the `mongodb+srv://` URI)                                                                                |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | 32-byte secret for session signing                                                                                                           |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | Secret for the bundled MinIO                                                                                                                 |
+| `RESEND_API_KEY`       | _(your key)_                 | Transactional email via Resend. Required for first-run setup unless you configure a global SMTP mailer (see [Global mailer](#global-mailer)) |
+
+### Baked-in defaults (override only if needed)
+
+| Variable           | Default                          | Description                          |
+| ------------------ | -------------------------------- | ------------------------------------ |
+| `PORT`             | `3100`                           | Backend listening port               |
+| `APP_URL`          | `http://localhost:3000`          | Public URL of the dashboard          |
+| `BACKEND_URL`      | `http://localhost:3100`          | Public URL of the backend API        |
+| `DOMAIN`           | `localhost`                      | Cookie domain                        |
+| `REDIS_URL`        | `redis://127.0.0.1:6379`         | Bundled Redis                        |
+| `S3_ENDPOINT`      | `http://127.0.0.1:9000`          | Bundled MinIO (server-to-server)     |
+| `S3_PUBLIC_URL`    | `http://localhost:9000/intlayer` | Public URL for browser asset loading |
+| `S3_BUCKET_NAME`   | `intlayer`                       | Bucket name                          |
+| `S3_ACCESS_KEY_ID` | `intlayer`                       | MinIO access key                     |
+
+### Optional (features degrade gracefully when absent)
+
+| Variable                                                 | Feature                                   |
+| -------------------------------------------------------- | ----------------------------------------- |
+| `OPENAI_API_KEY`                                         | AI-assisted translation and content audit |
+| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_*` | Billing and subscription management       |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`               | GitHub OAuth login                        |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`               | Google OAuth login                        |
+| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`               | GitLab OAuth login                        |
+| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`         | Microsoft OAuth login                     |
+
+### Global mailer
+
+By default, all transactional emails are sent through Resend using `RESEND_API_KEY`. Self-hosted deployments can instead route **every** email — including non-organization emails such as password resets and magic links — through a global mailer configured with environment variables.
+
+Set `MAIL_PROVIDER` to activate it. When unset, the default Resend mailer is used.
+
+| Variable             | Example                        | Description                                                       |
+| -------------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` or `resend`. Leave unset to use defaults |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. Accepts a bare address or `Name <email>` format    |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (required when `MAIL_PROVIDER=smtp`)                    |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (defaults to `587`)                                     |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Set `true` for port `465`                           |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP username (optional; omit for unauthenticated relays)         |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP password                                                     |
+
+> Precedence: an organization's own mailer (configured from the **Organization** dashboard) takes priority over the global mailer, which in turn takes priority over the default Resend key.
+
+---
+
+## Connecting your Intlayer project
+
+Once the stack is running, point your project at the self-hosted backend and dashboard instead of `intlayer.org`.
+
+### Project configuration
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * URL of the self-hosted CMS dashboard.
+     * Default: https://app.intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000
+
+    /**
+     * URL of the self-hosted backend API.
+     * Default: https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
+  },
+};
+
+export default config;
+```
+
+Set the environment variables in your project's `.env`:
+
+```sh
+INTLAYER_CMS_URL=http://localhost:3000
+INTLAYER_BACKEND_URL=http://localhost:3100
+INTLAYER_CLIENT_ID=<your-client-id>
+INTLAYER_CLIENT_SECRET=<your-client-secret>
+```
+
+Create access credentials in your self-hosted dashboard under **Projects → Access keys** at `http://localhost:3000/projects`.
+
+### `@intlayer/api` SDK
+
+When using the `@intlayer/api` SDK programmatically, pass `backendURL` explicitly:
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
+  },
+});
+
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+```
+
+---
+
+## Upgrading
+
+Pull the latest image and recreate the container. Your data is preserved in the named volume (MinIO/Redis) and in your Atlas cluster (MongoDB):
+
+```sh
+docker pull aymericzip/intlayer-selfhost
+docker stop intlayer && docker rm intlayer
+# re-run the `docker run …` command from Quick start
+```
+
+---
+
+## Backup and restore
+
+MongoDB data lives in your Atlas cluster — back it up with Atlas' own tools. The bundled local datastores live under the `intlayer-data` volume.
+
+### Backup
+
+```sh
+docker run --rm \
+  -v intlayer-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/intlayer-data.tar.gz /data
+```
+
+### Restore
+
+```sh
+docker run --rm \
+  -v intlayer-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar xzf /backup/intlayer-data.tar.gz -C /
+```
+
+---
+
+## Limitations
+
+- **MongoDB must be external (Atlas).** The backend connects only over `mongodb+srv://` (built from `DB_ID` / `DB_MDP` / `DB_CLUSTER`), so a plain `mongodb://host:27017` — including the container's own bundled `mongod` — cannot be used. Provide a MongoDB Atlas cluster.
+- **No custom domain.** All browser-facing `VITE_*` URLs are inlined into the app at build time, and the published image ships with `localhost` values. The dashboard must be accessed at `http://localhost:3000`; serving it on a public domain would require rebuilding the image with the target URLs baked in and is not supported out of the box.
+- **Email requires a working mailer.** First-run setup enforces email verification, so either `RESEND_API_KEY` or a [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) must be configured. After the first admin signs in, each organization can also configure its own SMTP or Resend mailer from the dashboard.
+
+---
+
+## Troubleshooting
+
+### Dashboard loads but the API resets the connection (`ERR_CONNECTION_RESET` on `:3100`)
+
+The backend crashed on startup and is not listening. The most common cause is a missing or invalid MongoDB connection: check that `DB_ID`, `DB_MDP`, and `DB_CLUSTER` are set and correct.
+
+```sh
+docker logs intlayer
+```
+
+Look for `MongoDB connection error` near the top of the log.
+
+### First account can't be verified
+
+Email verification is mandatory. Make sure a mailer is configured — either `RESEND_API_KEY`, or a [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) — then re-check your inbox (and spam). Without a working mailer, the verification link is never delivered. Delivery failures are logged by the backend (`docker logs intlayer`) with the underlying error message.
+
+### MinIO bucket missing
+
+The `init-minio` one-shot creates the bucket on first boot. If assets fail to load, restart the container so it runs again:
+
+```sh
+docker restart intlayer
+```
+
+---
+
+## Useful links
+
+- [Intlayer CMS documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
+- [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
+- [Docker Image (aymercizip/intlayer-selfhost)](https://hub.docker.com/repository/docker/aymercizip/intlayer-selfhost/general)

package/docs/en-GB/bundle_optimization.md

@@ -231,6 +231,9 @@ Next.js requires the `@intlayer/swc` plugin for the optimise (import rewrite) pa
 
 > This plugin is not installed by default as SWC plugins are still experimental for Next.js. This may change in the future.
 
+<Tabs>
+ <Tab value="npm">
+
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
 ```
@@ -247,6 +250,19 @@ pnpm add -D @intlayer/swc
 bun add -d @intlayer/swc
 ```
 
+ </Tab>
+ <Tab value="Crates.io (rust)">
+
+```toml fileName="Cargo.toml"
+[dependencies]
+intlayer-swc-plugin = "*"
+```
+
+[View on Crates.io](https://crates.io/crates/intlayer-swc-plugin)
+
+ </Tab>
+</Tabs>
+
 Once installed, Intlayer will automatically detect and use the plugin.
 
 For the **purge and minify** passes (field removal and field rename), install `@intlayer/babel` alongside it and add the Babel plugins. Because Next.js uses SWC for transformation but still evaluates `babel.config.js` for plugin config, the Babel plugins run as a pre-pass before SWC.

package/docs/en-GB/cli/index.md

@@ -125,7 +125,7 @@ To learn how to configure the available languages or other parameters, take a lo
 
 ### Authentication
 
-- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/login.md)** - Authenticate with the Intlayer CMS and get the access credentials
+- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md)** - Authenticate with the Intlayer CMS and get the access credentials
 
 ### Core Commands
 

package/docs/en-GB/cli/scan.md

@@ -150,10 +150,10 @@ await scan("https://example.com", {
 });
 ```
 
-For lower-level access, `scanWebsite` from `@intlayer/chokidar/scan` returns a structured `ScanResult` object:
+For lower-level access, `scanWebsite` from `@intlayer/engine/scan` returns a structured `ScanResult` object:
 
 ```ts
-import { scanWebsite } from "@intlayer/chokidar/scan";
+import { scanWebsite } from "@intlayer/engine/scan";
 
 const result = await scanWebsite("https://example.com", { deep: false });
 console.log(result.score, result.totalPageSize, result.events);