docs(v1): use posthog instead of segment (#13955)

shahednasser · web-flow · commit 65885df86af7 · 2025-11-04T14:53:49.000+02:00
* docs(v1): use posthog instead of segment

* added note to deployment guides

* fix tests
diff --git a/.github/workflows/docs-test.yml b/.github/workflows/docs-test.yml
@@ -41,6 +41,8 @@ jobs:
         env:
           NODE_OPTIONS: "--max-old-space-size=8192"
           API_URL: "https://docs.medusajs.com"
+          POSTHOG_API_KEY: "temp"
+          POSTHOG_HOST: "https://eu.i.posthog.com"
         run: yarn build:docs
         
   vale-docs:
diff --git a/www/apps/api-reference/.env.sample b/www/apps/api-reference/.env.sample
@@ -13,4 +13,6 @@ NEXT_PUBLIC_API_V2_URL=
 ALGOLIA_WRITE_API_KEY=
 NEXT_PUBLIC_AI_ASSISTANT_URL=
 NEXT_PUBLIC_AI_WEBSITE_ID=
-NEXT_PUBLIC_AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
+NEXT_PUBLIC_AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
+NEXT_PUBLIC_POSTHOG_API_KEY=
+NEXT_PUBLIC_POSTHOG_HOST=
diff --git a/www/apps/api-reference/package.json b/www/apps/api-reference/package.json
@@ -37,6 +37,7 @@
     "openapi-sampler": "^1.3.1",
     "openapi-types": "^12.1.3",
     "postcss": "8.4.27",
+    "posthog-js": "^1.285.1",
     "prism-react-renderer": "2.3.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
diff --git a/www/apps/api-reference/providers/index.tsx b/www/apps/api-reference/providers/index.tsx
@@ -18,7 +18,10 @@ type ProvidersProps = {
 
 const Providers = ({ children }: ProvidersProps) => {
   return (
-    <AnalyticsProvider writeKey={process.env.NEXT_PUBLIC_SEGMENT_API_KEY}>
+    <AnalyticsProvider
+      posthogApiKey={process.env.NEXT_PUBLIC_POSTHOG_API_KEY}
+      posthogHost={process.env.NEXT_PUBLIC_POSTHOG_HOST}
+    >
       <PageLoadingProvider>
         <ModalProvider>
           <ColorModeProvider>
diff --git a/www/apps/docs/.env.sample b/www/apps/docs/.env.sample
@@ -8,4 +8,6 @@ AI_API_ASSISTANT_TOKEN=
 AI_WEBSITE_ID=
 AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
 CLOUDINARY_CLOUD_NAME=
-BASE_PATH=
+BASE_PATH=
+POSTHOG_API_KEY=
+POSTHOG_HOST=
diff --git a/www/apps/docs/content/deployments/index.mdx b/www/apps/docs/content/deployments/index.mdx
@@ -7,7 +7,22 @@ import { getCategoryItems } from '@site/src/utils/get-first-category-item';
 
 # Deployment Overview
 
-In this document, you’ll learn about the different ways you can deploy your Medusa project.
+In this document, you’ll learn about the different ways you can deploy your Medusa v1 project.
+
+<Note title="Deploy with Medusa Cloud">
+
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+</Note>
 
 ## Overview
 
diff --git a/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md b/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md
@@ -5,7 +5,22 @@ addHowToData: true
 
 # Deploy Your Medusa Backend to DigitalOcean Apps
 
-In this document, you'll learn how to deploy your Medusa backend to a DigitalOcean App.
+In this document, you'll learn how to deploy your Medusa v1 backend to a DigitalOcean App.
+
+:::info[Deploy with Medusa Cloud]
+
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+:::
 
 DigitalOcean is a reliable hosting provider that provides different ways to host websites and servers. One way to host a backend is using their DigitalOcean App Platform.
 
diff --git a/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx b/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx
@@ -5,13 +5,22 @@ addHowToData: true
 
 # Deploy Your Medusa Backend on Heroku
 
-In this document, you'll learn how to deploy your Medusa backend on Heroku. Heroku is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud.
+In this document, you'll learn how to deploy your Medusa v1 backend on Heroku. Heroku is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud.
 
-Alternatively, you can use this button to deploy the Medusa backend to Heroku directly:
+<Note title="Deploy with Medusa Cloud">
 
-<a href="https://heroku.com/deploy?template=https://github.com/medusajs/medusa-starter-default/tree/feat/deploy-heroku" className="img-url">
-  <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy to Heroku" className="no-zoom-img" />
-</a>
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+</Note>
 
 ## Prerequisites
 
diff --git a/www/apps/docs/content/deployments/server/deploying-on-microtica.md b/www/apps/docs/content/deployments/server/deploying-on-microtica.md
@@ -5,7 +5,22 @@ addHowToData: true
 
 # Deploy Your Medusa Backend on Microtica
 
-In this document, you'll learn how to deploy your Medusa backend on your AWS account with Microtica.
+In this document, you'll learn how to deploy your Medusa v1 backend on your AWS account with Microtica.
+
+:::info[Deploy with Medusa Cloud]
+
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+:::
 
 :::note
 
diff --git a/www/apps/docs/content/deployments/server/deploying-on-railway.mdx b/www/apps/docs/content/deployments/server/deploying-on-railway.mdx
@@ -9,18 +9,26 @@ import MimeErrorTroubleshooting from "../../troubleshooting/mime-error.md"
 
 # Deploy Your Medusa Backend to Railway
 
-In this document, you’ll learn how to deploy your Medusa backend to Railway.
+In this document, you’ll learn how to deploy your Medusa v1 backend to Railway.
 
-## What is Railway
+<Note title="Deploy with Medusa Cloud">
 
-[Railway](https://railway.app/) is a hosting provider that you can use to deploy web applications and databases without having to worry about managing the full infrastructure.
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
 
-Railway provides a free trial (no credit card required) that allows you to deploy your Medusa backend along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes.
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
 
-<a 
-  href="https://railway.app/template/zC7eOq?referralCode=TW4Qi0" className="img-url no-zoom-img mb-2 inline-block">
-  <img src="https://railway.app/button.svg" alt="Deploy with Railway" className="no-zoom-img"/>
-</a>
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+</Note>
+
+## What is Railway
+
+[Railway](https://railway.app/) is a hosting provider that you can use to deploy web applications and databases without having to worry about managing the full infrastructure.
 
 <Note type="check">
 
diff --git a/www/apps/docs/content/deployments/server/general-guide.md b/www/apps/docs/content/deployments/server/general-guide.md
@@ -5,7 +5,22 @@ addHowToData: true
 
 # General Deployment Guide for Medusa Backend
 
-In this guide, you’ll learn the general steps you need to take when deploying your Medusa backend. This is useful when the [platform-specific deployment guides](./index.mdx) do not include your selected hosting provider.
+In this guide, you’ll learn the general steps you need to take when deploying your Medusa v1 backend. This is useful when the [platform-specific deployment guides](./index.mdx) do not include your selected hosting provider.
+
+:::info[Deploy with Medusa Cloud]
+
+This guide is intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+:::
 
 ## Prerequisites
 
diff --git a/www/apps/docs/content/deployments/server/index.mdx b/www/apps/docs/content/deployments/server/index.mdx
@@ -9,4 +9,19 @@ import DocCardList from '@theme/DocCardList';
 
 Find in this page guides to deploy your Medusa backend on different platforms.
 
+<Note title="Deploy with Medusa Cloud">
+
+The following guides are intended for Medusa v1 users. If you're a Medusa v2 user, consider using [Medusa Cloud](https://docs.medusajs.com/cloud). By using Medusa Cloud, you can avoid the complexities and challenges of self-hosting, while benefiting from automated deployment, scaling, and maintenance.
+
+With Medusa Cloud, you also maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+1. Push to deploy.
+2. Multiple testing environments.
+3. Preview environments for new PRs.
+4. Test on production-like data.
+
+Refer to the [Cloud vs. Self-Hosting comparison guide](https://docs.medusajs.com/cloud/comparison) for more details.
+
+</Note>
+
 <DocCardList />
diff --git a/www/apps/docs/docusaurus.config.js b/www/apps/docs/docusaurus.config.js
@@ -71,6 +71,14 @@ const config = {
         outputPath: path.join(__dirname, "src", "utils"),
       },
     ],
+    [
+      "posthog-docusaurus",
+      {
+        apiKey: process.env.POSTHOG_API_KEY,
+        appUrl: process.env.POSTHOG_HOST,
+        enableInDevelopment: false, // optional
+      },
+    ],
   ],
   themes: ["@docusaurus/theme-mermaid"],
   themeConfig: {
@@ -157,7 +165,8 @@ const config = {
       defaultFilters: ["docs"],
     },
     analytics: {
-      apiKey: process.env.SEGMENT_API_KEY || "temp",
+      apiKey: process.env.POSTHOG_API_KEY || "temp",
+      host: process.env.POSTHOG_HOST || "https://us.i.posthog.com",
     },
     prism: {
       defaultLanguage: "ts",
diff --git a/www/apps/docs/package.json b/www/apps/docs/package.json
@@ -43,6 +43,8 @@
     "lodash": "^4.17.21",
     "mdast-util-mdx": "^3.0.0",
     "postcss": "^8.4.21",
+    "posthog-docusaurus": "^2.0.5",
+    "posthog-js": "^1.285.1",
     "prism-react-renderer": "^2.3.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
diff --git a/www/apps/docs/src/providers/DocsProviders/index.tsx b/www/apps/docs/src/providers/DocsProviders/index.tsx
@@ -17,11 +17,11 @@ type DocsProvidersProps = {
 
 const DocsProviders = ({ children }: DocsProvidersProps) => {
   const {
-    analytics: { apiKey },
+    analytics: { apiKey, host },
   } = useThemeConfig() as ThemeConfig
 
   return (
-    <AnalyticsProvider writeKey={apiKey}>
+    <AnalyticsProvider posthogApiKey={apiKey} posthogHost={host}>
       <ColorModeProvider>
         <ModalProvider>
           <SearchProvider>
diff --git a/www/apps/docs/src/theme/Admonition/Layout/index.tsx b/www/apps/docs/src/theme/Admonition/Layout/index.tsx
@@ -47,7 +47,7 @@ function AdmonitionContent({
       )}
     >
       {title && (
-        <span className="txt-compact-medium-plus block mb-0.125">
+        <span className="text-compact-medium-plus block mb-docs_0.125 text-medusa-fg-base">
           {transformAdmonitionTitle(title)}
         </span>
       )}
diff --git a/www/apps/docs/src/types/index.d.ts b/www/apps/docs/src/types/index.d.ts
@@ -181,6 +181,7 @@ declare module "@medusajs/docs" {
     }
     analytics?: {
       apiKey: string
+      host?: string
     }
     aiAssistant?: {
       apiUrl: string
diff --git a/www/packages/docs-ui/package.json b/www/packages/docs-ui/package.json
@@ -54,13 +54,15 @@
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "next": "*",
+    "posthog-js": "*",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "dependencies": {
     "@medusajs/icons": "^1.2.0",
     "@medusajs/ui": "^2.4.1",
     "@octokit/request": "^8.1.1",
+    "@posthog/react": "^1.3.0",
     "@react-hook/resize-observer": "^1.2.6",
     "@segment/analytics-next": "^1.55.0",
     "@uidotdev/usehooks": "^2.4.1",
diff --git a/www/packages/docs-ui/src/components/Feedback/index.tsx b/www/packages/docs-ui/src/components/Feedback/index.tsx
@@ -59,12 +59,9 @@ export const Feedback = ({
     : showForm
     ? inlineQuestionRef
     : inlineFeedbackRef
-  const { loaded, track } = useAnalytics()
+  const { track } = useAnalytics()
 
   function handleFeedback(e: React.MouseEvent<HTMLButtonElement, MouseEvent>) {
-    if (!loaded) {
-      return
-    }
     const feedback = (e.target as Element).classList.contains("positive")
     setPositiveFeedback(feedback)
     setShowForm(true)
diff --git a/www/packages/docs-ui/src/providers/AiAssistant/index.tsx b/www/packages/docs-ui/src/providers/AiAssistant/index.tsx
@@ -1,7 +1,6 @@
 "use client"
 
 import React, { createContext, useContext } from "react"
-import { useAnalytics } from "@/providers"
 import { AiAssistant } from "@/components"
 import { RecaptchaAction, useRecaptcha } from "../../hooks/use-recaptcha"
 
@@ -30,7 +29,6 @@ export const AiAssistantProvider = ({
   websiteId,
   children,
 }: AiAssistantProviderProps) => {
-  const { analytics } = useAnalytics()
   const { execute: getReCaptchaToken } = useRecaptcha({
     siteKey: recaptchaSiteKey,
   })
@@ -77,7 +75,6 @@ export const AiAssistantProvider = ({
       JSON.stringify({
         question_id: questionId,
         reaction,
-        user_identifier: analytics?.user().anonymousId() || "",
       })
     )
   }
diff --git a/www/packages/docs-ui/src/providers/Analytics/index.tsx b/www/packages/docs-ui/src/providers/Analytics/index.tsx
diff --git a/www/yarn.lock b/www/yarn.lock
