From bf522217d7c00ce40ed49edbcd3131b977fb8f1f Mon Sep 17 00:00:00 2001
From: Multinite <145994855+Multinite@users.noreply.github.com>
Date: Sun, 15 Dec 2024 04:30:42 +1000
Subject: [PATCH] docs: add FAQ page to docs (#875)

---
 .vscode/settings.json               |  3 ++
 docs/app/docs/[[...slug]]/page.tsx  |  3 ++
 docs/components/sidebar-content.tsx |  6 +++
 docs/content/docs/reference/faq.mdx | 84 +++++++++++++++++++++++++++++
 4 files changed, 96 insertions(+)
 create mode 100644 docs/content/docs/reference/faq.mdx

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 7a9390c1..49c24b58 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -22,5 +22,8 @@
 	},
 	"[typescriptreact]": {
 		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[mdx]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
 	}
 }
diff --git a/docs/app/docs/[[...slug]]/page.tsx b/docs/app/docs/[[...slug]]/page.tsx
index 2e29f614..38cfcecf 100644
--- a/docs/app/docs/[[...slug]]/page.tsx
+++ b/docs/app/docs/[[...slug]]/page.tsx
@@ -15,6 +15,7 @@ import Link from "next/link";
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import { File, Folder, Files } from "fumadocs-ui/components/files";
 import { createTypeTable } from "fumadocs-typescript/ui";
+import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 const { AutoTypeTable } = createTypeTable();
 
@@ -79,6 +80,8 @@ export default async function Page({
 						Features,
 						ForkButton,
 						DatabaseTable,
+						Accordion,
+						Accordions,
 						iframe: (props) => (
 							<iframe {...props} className="w-full h-[500px]" />
 						),
diff --git a/docs/components/sidebar-content.tsx b/docs/components/sidebar-content.tsx
index 7b53e782..f40bb9a8 100644
--- a/docs/components/sidebar-content.tsx
+++ b/docs/components/sidebar-content.tsx
@@ -1,4 +1,5 @@
 import {
+	CircleHelp,
 	Key,
 	LucideAArrowDown,
 	LucideIcon,
@@ -1105,6 +1106,11 @@ export const contents: Content[] = [
 				href: "/docs/reference/security",
 				icon: () => <ShieldCheck className="w-4 h-4 text-current" />,
 			},
+			{
+				title: "FAQ",
+				href: "/docs/reference/faq",
+				icon: () => <CircleHelp className="w-4 h-4 text-current" />,
+			},
 		],
 	},
 ];
diff --git a/docs/content/docs/reference/faq.mdx b/docs/content/docs/reference/faq.mdx
new file mode 100644
index 00000000..2c1e1a09
--- /dev/null
+++ b/docs/content/docs/reference/faq.mdx
@@ -0,0 +1,84 @@
+---
+title: FAQ
+description: Frequently asked questions about Better-Auth.
+---
+
+This page contains frequently asked questions about common bugs or questions around Better-Auth.
+
+<Accordions>
+  <Accordion title="createAuthClient not working">
+  When encountering `createAuthClient` related errors, make sure to have the correct import path as it varies based on enviroment.
+
+If you're using the auth client on react front-end, you'll need to import it from `/react`:
+
+```ts title="component.ts"
+import { createAuthClient } from "better-auth/react";
+```
+
+Where as if you're using the auth client in Next.js middelware, server-actions, server-components or anything server-related, you'll likely need to import it from `/client`:
+
+```ts title="server.ts"
+import { createAuthClient } from "better-auth/client";
+```
+
+  </Accordion>
+  <Accordion title="getSession not working">
+If you're running `getSession` from the server side (such as in a React Server Component), you need to pass headers for it to work.
+
+```ts title="server.ts"
+const result = authClient.getSession({
+  fetchOptions: { headers: yourHeaders },
+});
+```
+
+If you're using Next.js, you're likely able to access `headers()` from `next/headers`: (<Link href="https://nextjs.org/docs/app/api-reference/functions/headers">Read more here</Link>)
+
+```ts title="server.ts"
+import { headers } from "next/headers";
+//...
+const result = authClient.getSession({
+  fetchOptions: { headers: await headers() },
+});
+```
+
+    </Accordion>
+
+    <Accordion title="Adding custom fields to the users table">
+
+Better Auth provides a type-safe way to extend the user and session schemas, take a look at our docs on <Link href="/docs/concepts/database#extending-core-schema">extending core schema</Link>.
+
+</Accordion>
+
+<Accordion title="Difference between getSession and useSession">
+Both `useSession` and `getSession` instances are used fundamentally different based on the situation.
+
+`useSession` is a hook, meaning it can trigger re-renders whenever session data changes.
+
+If you have UI you need to change based on user or session data, you can use this hook.
+
+<Callout type="warn">
+  For performance reasons, do not use this hook on your `layout.tsx` file. We
+  recommend using RSC and use your server auth instance to get the session data
+  via `auth.api.getSession`.
+</Callout>
+
+`getSession` returns a promise containing data and error.
+
+For all other situations where you shouldn't use `useSession`, is when you should be using `getSession`.
+
+<Callout type="info">
+   `getSession` is avaliable on both server and client auth instances.
+   Not just the latter.
+</Callout>
+</Accordion>
+
+<Accordion title="Common Typescript Errors">
+A common Typescript error we come across from users of Better Auth is due to their tsconfig.
+
+If you're facing Better-Auth related errors, ensure your tsconfig has `declarations` set to `false`, and `strict` set to `true`.
+
+You can learn more in our <Link href="/docs/concepts/typescript#typescript-config">Typescript docs</Link>.
+
+</Accordion>
+
+</Accordions>