Update docs with a new improved Quickstart guide (#725)

* update quickstart

* update quickstart and add react

* add screenshot

* update images and comments

* added image

* fill placeholder

* fix build error

* updating wording

---------

Co-authored-by: Matthias Nannt <mail@matthiasnannt.com>

apps/formbricks-com/lib/docsNavigation.ts

@@ -10,10 +10,11 @@ const navigation = [
   {
     title: "Getting Started",
     links: [
-      { title: "Quickstart", href: "/docs/getting-started/quickstart" },
+      { title: "Quickstart: In app", href: "/docs/getting-started/quickstart-in-app-survey" },
       { title: "Next.js App Dir", href: "/docs/getting-started/nextjs-app" },
       { title: "Next.js Pages Dir", href: "/docs/getting-started/nextjs-pages" },
-      { title: "Setup with Vue.js", href: "/docs/getting-started/vuejs" },
+      { title: "React", href: "/docs/getting-started/react" },
+      { title: "Vue.js", href: "/docs/getting-started/vuejs" },
     ],
   },
   {

apps/formbricks-com/next.config.mjs

@@ -100,6 +100,11 @@ const nextConfig = {
         destination: "/docs/actions/code",
         permanent: true,
       },
+      {
+        source: "/docs/quickstart",
+        destination: "/docs/quickstart-in-app-survey",
+        permanent: true,
+      },
       {
         source: "/pmf",
         destination: "/",

apps/formbricks-com/pages/docs/getting-started/nextjs-app/index.mdx

@@ -22,7 +22,7 @@ Before getting started, make sure you have:
 
 <Image src={SetupChecklist} alt="Step 2 - Setup Checklist" quality="100" className="rounded-lg" />
 
-## Installing Formbricks SDK
+## 1. Installing Formbricks SDK
 
 First, you need to install the Formbricks SDK using one of the following commands:
 
@@ -34,7 +34,7 @@ yarn add @formbricks/js
 pnpm add @formbricks/js
 ```
 
-## Integrating with Next.js 13 App Directory
+## 2. Integrating with Next.js 13 App Directory
 
 The Next.js 13 app directory requires us to initialize Formbricks differently than the pages directory. Specifically, the app directory server-side renders components by default, and the formbricks-js library is a client-side library. To make these work together, create a `formbricks.tsx` file (or `formbricks.js` if you don't use Typescript) and set up the FormbricksProvider with the 'use client' directive:
 
@@ -82,7 +82,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-## Validate your setup
+## 3. Validate your setup
 
 Once you have completed the steps above, you can validate your setup by checking the **Setup Checklist** in the Settings. Your widget status indicator should go from this:
 

apps/formbricks-com/pages/docs/getting-started/nextjs-pages/index.mdx

@@ -22,7 +22,7 @@ Before getting started, make sure you have:
 
 <Image src={SetupChecklist} alt="Step 2 - Setup Checklist" quality="100" className="rounded-lg" />
 
-## Installing Formbricks SDK
+## 1. Installing Formbricks SDK
 
 First, you need to install the Formbricks SDK using one of the following commands:
 
@@ -34,7 +34,7 @@ yarn add @formbricks/js
 pnpm add @formbricks/js
 ```
 
-## Integrating with Next.js 13 Pages Directory
+## 2. Integrating with Next.js 13 Pages Directory
 
 Update your Pages component in the \_app.ts file like so:
 
@@ -75,7 +75,7 @@ export default function Pages({ Component, pageProps }: PagesProps) {
 1. First we need to initialize the Formbricks SDK, making sure it only runs on the client side.
 2. To connect the Next.js router to Formbricks and ensure the SDK can keep track of every page change, we are registering the route change event.
 
-## Validate your setup
+## 3. Validate your setup
 
 Once you have completed the steps above, you can validate your setup by checking the **Setup Checklist** in the Settings. Your widget status indicator should go from this:
 

apps/formbricks-com/pages/docs/getting-started/quickstart-in-app-survey/index.mdx

@@ -0,0 +1,137 @@
+import { Layout } from "@/components/docs/Layout";
+import Image from "next/image";
+
+import I1 from "./1-in-app-survey-or-popup-survey-setup.webp";
+import I2 from "./2-settings-for-survey-popup-in-app-for-feedback.webp";
+import I3 from "./3-web-app-survey-settings-for-in-app-survey-popup.webp";
+import I4 from "./4-in-app-survey-trigger-for-popup-survey.webp";
+import I5 from "./5-options-survey-popup-in-app-for-feedback.webp";
+import I6 from "./6-setup-in-app-survey-popup-feedback-box.webp";
+import I7 from "./7-in-app-survey-popup-for-feedback.webp";
+import I8 from "./8-pop-up-form-in-web-app-survey.webp";
+import I9 from "./9-set-up-in-app-micro-survey-popup.webp";
+import I10 from "./10-micro-survey-pop-up-in-app.webp";
+import I11 from "./11-survey-logs-in-app-survey-popup.webp";
+import ReactApp from "../react/1-in-app-survey-react-app-popup-form.webp";
+
+export const meta = {
+  title: "Collect in app survey responses in 10 minutes",
+  description: "Get your first in app survey response in 10 minutes.",
+};
+
+In app surveys have 6-10x better conversion rates than emailed out surveys. This tutorial explains how to run an in app survey in your web app in 10 to 15 minutes. Let’s go!
+
+## 1. Create a free Formbricks Cloud account
+
+While you can [self-host](/docs/self-hosting/deployment) Formbricks, the quickest and easiest way to get started is with the free Cloud plan. Just [sign up here](https://app.formbricks.com/auth/signup) and click through the onboarding, until you’re here:
+
+<Image src={I1} alt="Choose in app survey template" quality="100" className="rounded-lg" />
+
+## 2. Create your first survey
+
+To be able to see a survey in your app, you need to create one. We’ll choose one of the templates and head over to the survey settings:
+
+<Image src={I2} alt="Settings for popup survey inside web app" quality="100" className="rounded-lg" />
+
+As you can see in the orange note here, we have not yet connected Formbricks Cloud with our app. We will do so in just a minute, let’s first setup the survey correctly.
+
+Select “Web App” in the How to ask settings:
+
+<Image src={I3} alt="Survey settings for popup micro surve" quality="100" className="rounded-lg" />
+
+Scroll down to Survey Trigger and choose “New Session”. This will cause this survey to appear when the Formbricks Widget tracks a new user session:
+
+<Image
+  src={I4}
+  alt="In app survey trigger for feedback popup micro survey"
+  quality="100"
+  className="rounded-lg"
+/>
+
+In **Recontact Options** we choose the following settings, so that we can play around with the survey more easily. By default, each survey will be shown only once to each user to prevent survey fatigue:
+
+<Image src={I5} alt="Options for survey popup in app micro survey" quality="100" className="rounded-lg" />
+
+Now hit **Publish** and you’ll be forwarded to the Summary Page. This is where you’ll find the responses to this survey. On the Summary Page click through to the Setup Checklist:
+
+<Image src={I6} alt="pop up survey settings for inapp web survey" quality="100" className="rounded-lg" />
+
+## 3. Set up the Formbricks Widget in your app
+
+On the Setup Checklist you have two elements. At the top you find the Widget Status Indicator. Once your app is connected to Formbricks Cloud successfully, this will turn green:
+
+<Image src={I7} alt="feedback popup in app survey" quality="100" className="rounded-lg" />
+
+In the manual below, this code snippet contains all the information you need:
+
+- The **Environment ID** of your current Formbricks workspace
+- The **API Host** which is ‘https://app.formbricks.com’ for Cloud users
+
+<Image src={I8} alt="settings for in app survey popping up" quality="100" className="rounded-lg" />
+
+## Load Formbricks widget in your app
+
+In a local instance of your app, you'll embed the Formbricks Widget. Dependent on your frontend tech, the setup differs a bit:
+
+- [Next.JS App Directory](/docs/getting-started/nextjs-app)
+- [Next.JS Pages Directory](/docs/getting-started/nextjs-pages)
+- [React (Create React App)](/docs/getting-started/react)
+- [Vue.JS](/docs/getting-started/vuejs)
+
+## 4. Restart your app and open browser console
+
+Now, restart your app in your terminal to make sure the widget is loaded. Once its loaded, open the browser console to see the Formbricks debug logs. If you did everything right, you should now see your survey in the lower right corner:
+
+<Image
+  src={ReactApp}
+  alt="In app survey in React app for micro surveys"
+  quality="100"
+  className="rounded-lg"
+/>
+
+## 5. Most frequent errors and how to debug them
+
+In case you don’t see your survey right away, here's what you can do. Go through these in orderly to find the error fast:
+
+### A. Formbricks Cloud and your app are not connected properly.
+
+Go back to [app.formbricks.com](http://app.formbricks.com) and go to the Setup Checklist in the Settings. If the status is still indicated as “Not connected” your app hasn't yet pinged the Formbricks Cloud:
+
+<Image
+  src={I9}
+  alt="setup checklist ui of survey popup for in app surveys"
+  quality="100"
+  className="rounded-lg"
+/>
+**How to fix it:**
+
+1. Check if your app loads the Formbricks widget correctly. Make sure you have `debug` mode enabled in your integration and you should see the Formbricks debug logs in your browser console while being in your app (right click in the browser, `Inspect`, switch to the console tab). If you don’t see them, double check your integration or if you are unable to solve this issue, please [join our Discord](https://formbricks.com/discord) and we’ll help you out.
+
+---
+
+### B. Survey not loaded
+
+If your app is connected with Formbricks Cloud, the survey might have not been loaded properly. Check the debug logs and search for the list of surveys loaded. It should look like so:
+
+<Image src={I11} alt="survey logs for in app survey pop up micro" quality="100" className="rounded-lg" />
+
+**How to fix it:**
+
+The widget only loads surveys which are **public** and **in progress**. Go to Formbricks Cloud and to the Survey Summary page. Check if your survey is live:
+
+<Image src={I10} alt="ui of survey popup for in app micro surveys" quality="100" className="rounded-lg" />
+
+---
+
+### C. Survey not triggered
+
+If the survey is loaded by the widget it might not have been triggered properly.
+
+**How to fix:**
+
+1. Open your local app in an incognito tab or window. The New Session event is only fired if a user was inactive for 60 minutes or was logged out of Formbricks via formrbicks.logout().
+2. Check the debug logs for “Event ‘New Session” tracked”. If you see it in the logs and the survey still did not get displayed, [please let us know.](mailto:support@formbricks.com)
+
+That should fix it! If not, please [join our Discord](https://formbricks.com/discord)! We’re more than happy to help you get started 😊
+
+export default ({ children }) => <Layout meta={meta}>{children}</Layout>;

apps/formbricks-com/pages/docs/getting-started/quickstart/index.mdx

@@ -1,95 +0,0 @@
-import { Layout } from "@/components/docs/Layout";
-
-export const meta = {
-  title: "Quickstart",
-  description:
-    "Get started with Formbricks: Choose self-hosted or cloud, create an account, and follow our quickstart guide to set up in-product micro-surveys with ease.",
-};
-
-Welcome to Formbricks! In this quickstart guide, we'll walk you through the initial steps to get up and running with our in-product micro-surveys. Choose between self-hosted and cloud options, create an account, and set up the JavaScript widget. Let's dive in!
-
-## Step 1: Choose between self-hosted and cloud
-
-First, you need to decide whether you want to use the self-hosted or cloud version of Formbricks.
-
-- **Self-hosted**: If you prefer to host Formbricks on your own servers, check out the dedicated [Self-hosted Documentation](/docs/self-hosting/deployment) page.
-- **Cloud**: For a hassle-free experience, choose our cloud offering, which takes care of server maintenance and updates for you. [Sign Up now.](https://app.formbricks.com/auth/signup)
-
-## Step 2: Create an account
-
-1. Visit the Formbricks Sign up page.
-2. Enter your email address, choose a password, and click **Sign Up** to create your account. Alternatively you can sign up using your GitHub account.
-
-## Step 3: Switch to the Development Environment
-
-In Formbricks, you can work in different environments to manage your surveys and settings. We recommend using the **Development environment** for your local testing and staging environments to keep your Production environment and it's data clean. To get started, switch to the **Development Environment**:
-
-1. Log in to your Formbricks dashboard.
-2. Click the your profile picture in the top right corner and in the dropdown under your current Environment select **Development**.
-3. Select **Development** from the list.
-
-## Step 4: Set up the JavaScript widget
-
-You can find all the setup instructions as well as a check if your installation was successful in the **Setup Checklist** in the Formbricks settings.
-
-### HTML
-
-Add the following script to the `<head>` tag of your HTML file:
-
-```html
-<script type="text/javascript">
-  !(function () {
-    var t = document.createElement("script");
-    (t.type = "text/javascript"),
-      (t.async = !0),
-      (t.src = "https://unpkg.com/@formbricks/js@^1.0.0/dist/index.umd.js");
-    var e = document.getElementsByTagName("script")[0];
-    e.parentNode.insertBefore(t, e),
-      setTimeout(function () {
-        window.formbricks = window.js;
-        window.formbricks.init({
-          environmentId: "your-environment-id",
-          apiHost: "https://app.formbricks.com",
-        });
-      }, 500);
-  })();
-</script>
-```
-
-Replace your-environment-id with your actual environment ID. You can find your environment ID in the **Setup Checklist** in the Formbricks settings.
-
-### Npm
-
-1. Install the Formbricks package using npm:
-
-```bash
-npm install -s @formbricks/js
-```
-
-2. Import Formbricks and initialize the widget in your main component (e.g., App.tsx or App.js):
-
-```javascript
-import formbricks from "@formbricks/js";
-
-if (typeof window !== "undefined") {
-  formbricks.init({
-    environmentId: "your-environment-id",
-    apiHost: "https://app.formbricks.com",
-  });
-}
-```
-
-Replace your-environment-id with your actual environment ID. You can find your environment ID in the **Setup Checklist** in the Formbricks settings.
-
-For more detailed guides for different frameworks, check out our [Next.js](/docs/getting-started/nextjs) and [Vue.js](/docs/getting-started/vuejs) guides.
-
-## Step 5: Verify your setup
-
-After setting up the widget, head back to the Formbricks dashboard:
-
-1. Navigate to **Settings** in the top menubar.
-2. Check the **Setup Checklist** to ensure everything is working correctly.
-
-If you see confetti and a green box saying "Receiving data" you've successfully set up Formbricks. You're ready to start creating and customizing your in-product surveys.
-
-export default ({ children }) => <Layout meta={meta}>{children}</Layout>;

apps/formbricks-com/pages/docs/getting-started/react/index.mdx

@@ -0,0 +1,92 @@
+import { Layout } from "@/components/docs/Layout";
+import Image from "next/image";
+
+import ReactApp from "./1-in-app-survey-react-app-popup-form.webp";
+import SetupChecklist from "./env-id.png";
+import WidgetNotConnected from "./widget-not-connected.png";
+import WidgetConnected from "./widget-connected.png";
+
+export const meta = {
+  title: "Setting up Formbricks SDK with React",
+  description: "Setting up Formbricks with plain React",
+};
+
+## Prerequisites
+
+Before getting started, make sure you have:
+
+1. A React application created with 'create-react-app'.
+2. A Formbricks account with access to your environment ID and API host. You can find these in the **Setup Checklist** in the Settings:
+
+<Image src={SetupChecklist} alt="Step 2 - Setup Checklist" quality="100" className="rounded-lg" />
+
+## 1. Installing Formbricks SDK
+
+First, you need to install the Formbricks SDK using one of the following commands:
+
+```bash
+npm install --save @formbricks/js
+# or
+yarn add @formbricks/js
+# or
+pnpm add @formbricks/js
+```
+
+## 2. Integrating with React
+
+Update your App.js file like so:
+
+```tsx
+import formbricks from "@formbricks/js";
+import "./App.css";
+import logo from "./logo.svg";
+
+if (typeof window !== "undefined") {
+  formbricks.init({
+    environmentId: "cllc820rs01-REPLACE-ME", // replace with your env ID!
+    apiHost: "https://app.formbricks.com", // update if you're self-hosting
+    debug: true, // remove when in production
+  });
+}
+
+function App() {
+  return (
+    <div className="App">
+      <header className="App-header">
+        <img src={logo} className="App-logo" alt="logo" />
+        <p>
+          Edit <code>src/App.js</code> and save to reload.
+        </p>
+        <a className="App-link" href="https://reactjs.org" target="_blank" rel="noopener noreferrer">
+          Learn React
+        </a>
+      </header>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## What are we doing here?
+
+The app initializes 'formbricks' when it's loaded in a browser environment (due to the typeof window !== "undefined" check) and then renders your components or content.
+
+<Image
+  src={ReactApp}
+  alt="In app survey in React app for micro surveys"
+  quality="100"
+  className="rounded-lg"
+/>
+
+## 3. Validate your setup
+
+Once you have completed the steps above, you can validate your setup by checking the **Setup Checklist** in the Settings. Your widget status indicator should go from this:
+
+<Image src={WidgetNotConnected} alt="Widget isnt connected" quality="100" className="rounded-lg" />
+
+To this:
+
+<Image src={WidgetConnected} alt="Widget is connected" quality="100" className="rounded-lg" />
+
+export default ({ children }) => <Layout meta={meta}>{children}</Layout>;

apps/formbricks-com/pages/docs/getting-started/vuejs/index.mdx

@@ -19,7 +19,7 @@ Before proceeding, ensure you have the following:
 1. A Vue.js application set up and ready to go.
 2. A Formbricks account with an `environmentId` and `apiHost` for your application. You can find these in the Setup Checklist in the Settings.
 
-## Installation
+## 1. Installation
 
 To get started, install the Formbricks SDK using your preferred package manager:
 
@@ -31,7 +31,7 @@ yarn add @formbricks/js
 pnpm add @formbricks/js
 ```
 
-## Integration
+## 2. Integration with Vue.js
 
 1. Create a new file called \`formbricks.js\` inside the \`src\` folder of your Vue.js application, and add the following code to initialize the Formbricks SDK: