` blocks there.
+
+Q: Why can the docs copy button throw `Cannot set properties of null (setting 'textContent')`?
+A: In `docs-mintlify/snippets/home-prompt-island.jsx`, reading `event.currentTarget` after `await navigator.clipboard.writeText(...)` can produce null in runtime event wrappers. Capture `const button = event.currentTarget` before awaiting.
+
+Q: How should the docs Explore Apps grid support both light and dark themes?
+A: In `docs-mintlify/snippets/docs-apps-home-grid.jsx`, use light-first container/tile styles with explicit `dark:*` overrides (including `dark:invert` for icons) so light mode remains readable while dark mode keeps the neon tile look.
+
+Q: How can docs-mintlify add an Apps sidebar filter without React hooks?
+A: In `docs-mintlify/snippets/docs-apps-home-grid.jsx`, inject a compact `` under the sidebar "Apps" header via DOM (`#navigation-items` + `.sidebar-group-header` text match), filter that group's `
- ` rows on `input`, and observe `document.documentElement.classList` with `MutationObserver` to swap light/dark inline styles when `html` toggles between `light` and `dark`.
+
+Q: Why did Explore Apps look light in dark mode even with `dark:bg` set on the container?
+A: `bg-gradient-to-b` applies a background image, and `dark:bg-[#...]` only changes background color, so the light gradient image stays visible. Use `dark:from[...] dark:to[...]` (or a full dark gradient/image override) so dark mode replaces the gradient itself.
+
+Q: What should we do when changing docs sidebar search injection from block to inline?
+A: Remove legacy `div[data-apps-sidebar-search='true']` nodes before adding the new inline header input; otherwise old and new filters can coexist after hot reload and render duplicate search boxes.
+
+Q: What caused the Explore Apps hover layout shift?
+A: The app link wrapper in `docs-mintlify/snippets/docs-apps-home-grid.jsx` used `hover:-translate-y-0.5`, which makes tiles physically move on hover and looks like layout jank. Removing the translate/transform from the wrapper keeps hover effects without perceived shifting.
+
+Q: How should the sidebar Apps filter behave when there are no matches?
+A: In `docs-mintlify/snippets/docs-apps-home-grid.jsx`, track visible rows while filtering and show a small inline empty state (`No more results. Clear filter`) when query is non-empty and visible count is zero; wire `Clear filter` to reset the input, rerun filtering, and refocus the input.
diff --git a/docs-mintlify/index.mdx b/docs-mintlify/index.mdx
index 00e7629f0..178331d71 100644
--- a/docs-mintlify/index.mdx
+++ b/docs-mintlify/index.mdx
@@ -4,6 +4,9 @@ description: "Stack Auth documentation for setup, components, SDK usage, and RES
sidebarTitle: "Overview"
---
+import { HomePromptIsland } from "/snippets/home-prompt-island.jsx";
+import { DocsAppsHomeGrid } from "/snippets/docs-apps-home-grid.jsx";
+
export const SectionLink = ({ href, children }) => (
{children}
);
@@ -12,78 +15,7 @@ export const ChipLink = ({ href, children }) => (
{children}
);
-export const CardTitle = ({ href, children }) => (
- {children}
-);
-
-export const CardChip = ({ href, children }) => (
- {children}
-);
-
-
-
-
-
-
-
-
-
-
-
-
- Ship auth without
-
-
- Ship auth without
- rebuilding the basics
-
- - Learn how to set up Stack Auth, drop in prebuilt components, use the - SDK, and integrate any backend through the REST API. -
- -
-
-
- Follow the [setup guide](/guides/getting-started/setup) to initialize Stack Auth in your app.
-
- ```bash
- npx @stackframe/stack-cli@latest init
- ```
-
-
- Use the [setup guide](/guides/getting-started/setup) to configure prebuilt auth interfaces and handlers.
-
-
- Reach for the [SDK overview](/sdk/overview) when you need hooks, objects, and typed access to users, teams, and sessions.
-
-
- Use the [REST API overview](/api/overview) for backend integrations, custom clients, and non-Next.js environments.
-
-
-
-
+
-
-
- Quick Start
-- Go from a new project to authenticated users with the shortest path through the docs. -
-
@@ -109,81 +41,58 @@ export const CardChip = ({ href, children }) => (
- Components
- Explore Apps
+
+
+ {/* Going Further */}
+ Drop-in UI for sign-in, sign-up, account settings, and team switching.
++ Open app guides from a home-screen style quick access grid, modeled after dashboard Overview. +
+
+
+ Going Further
+
{/* SDK Reference */}
- + Configure Stack App deeply, integrate your backend, and use lower-level interfaces where needed. +
- SignIn / SignUp
+ Stack App
+ Backend Integration
+ Local Development
+
SDK Reference
-
useUser
- Types
StackApp
+ User Type
+
+
+
+ {/* REST API */}
+
-
- {/* Branch divider */}
- Hooks, types, and objects for reading and writing user data in code.
++ Use hooks, objects, and types to read and write auth data directly in your app code. +
+
+ REST API
+
+ Integrate Stack Auth from any backend or language through HTTP endpoints and webhook flows. +
+
+ Overview
+ Webhooks
+ Backend Integration
-
- Then pick your path
-
-
-
- {/* Branching cards */}
-
-
-
-
- Going Further
-
- Stack App configuration, backend integration, local development, metadata.
-
- Stack App
- Local dev
- Backend
-
-
- Apps
-
- Authentication, emails, payments, webhooks, API keys.
-
- Auth
- Emails
- Payments
-
-
- REST API
-
- HTTP endpoints for any backend or language.
-
- REST API
- Webhooks
-
- Explore Apps
- -
diff --git a/docs-mintlify/snippets/docs-apps-home-grid.jsx b/docs-mintlify/snippets/docs-apps-home-grid.jsx
new file mode 100644
index 000000000..989e3be1e
--- /dev/null
+++ b/docs-mintlify/snippets/docs-apps-home-grid.jsx
@@ -0,0 +1,258 @@
+export const DocsAppsHomeGrid = () => {
+ const labelOverrides = new Map([
+ ["api-keys", "API Keys"],
+ ["rbac", "RBAC"],
+ ]);
+
+ const toStartCase = (value) => {
+ const override = labelOverrides.get(value);
+ if (override != null) {
+ return override;
+ }
+ return value
+ .split("-")
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+ .join(" ");
+ };
+
+ const fallbackApps = [
+ { name: "Authentication", href: "/guides/apps/authentication/overview", iconSrc: "/images/app-icons/authentication.svg" },
+ { name: "Emails", href: "/guides/apps/emails/overview", iconSrc: "/images/app-icons/emails.svg" },
+ { name: "Payments", href: "/guides/apps/payments/overview", iconSrc: "/images/app-icons/payments.svg" },
+ { name: "Analytics", href: "/guides/apps/analytics/overview", iconSrc: "/images/app-icons/analytics.svg" },
+ { name: "Teams", href: "/guides/apps/teams/overview", iconSrc: "/images/app-icons/teams.svg" },
+ { name: "Fraud Protection", href: "/guides/apps/fraud-protection/overview", iconSrc: "/images/app-icons/fraud-protection.svg" },
+ { name: "RBAC", href: "/guides/apps/rbac/overview", iconSrc: "/images/app-icons/rbac.svg" },
+ { name: "API Keys", href: "/guides/apps/api-keys/overview", iconSrc: "/images/app-icons/api-keys.svg" },
+ { name: "Data Vault", href: "/guides/apps/data-vault/overview", iconSrc: "/images/app-icons/data-vault.svg" },
+ { name: "Webhooks", href: "/guides/apps/webhooks/overview", iconSrc: "/images/app-icons/webhooks.svg" },
+ { name: "Launch Checklist", href: "/guides/apps/launch-checklist/overview", iconSrc: "/images/app-icons/launch-checklist.svg" },
+ ];
+
+ const getAppsFromSidebar = () => {
+ if (typeof document === "undefined") {
+ return fallbackApps;
+ }
+
+ const sidebarRoot = document.querySelector("ul#sidebar-group");
+ if (sidebarRoot == null) {
+ return fallbackApps;
+ }
+
+ const candidateLinks = sidebarRoot.querySelectorAll('a[href^="/guides/apps/"]');
+ const appItems = [];
+ const seenHrefs = new Set();
+
+ for (const link of candidateLinks) {
+ const href = link.getAttribute("href");
+ if (href == null || seenHrefs.has(href)) {
+ continue;
+ }
+
+ const iconImage = link.querySelector("img");
+ if (iconImage == null) {
+ continue;
+ }
+
+ const textContent = link.textContent?.replace(/\s+/g, " ").trim();
+ const slug = href.replace(/^\/guides\/apps\//, "").split("/")[0];
+ const iconSrc = iconImage.getAttribute("src") ?? `/images/app-icons/${slug}.svg`;
+ const name = textContent != null && textContent.length > 0 ? textContent : toStartCase(slug);
+
+ seenHrefs.add(href);
+ appItems.push({ name, href, iconSrc });
+ }
+
+ if (appItems.length === 0) {
+ return fallbackApps;
+ }
+
+ return appItems;
+ };
+
+ const appLinks = getAppsFromSidebar();
+ const onExploreSearchInput = (event) => {
+ const input = event.currentTarget;
+ const root = input.closest("[data-explore-apps-root='true']");
+ if (root == null) {
+ return;
+ }
+
+ const query = input.value.trim().toLowerCase();
+ const cards = root.querySelectorAll("[data-explore-app-card='true']");
+ let visibleCount = 0;
+ for (const card of cards) {
+ const appName = (card.getAttribute("data-app-name") ?? "").toLowerCase();
+ const isVisible = query.length === 0 || appName.includes(query);
+ card.style.display = isVisible ? "" : "none";
+ if (isVisible) {
+ visibleCount += 1;
+ }
+ }
+
+ const emptyState = root.querySelector("[data-explore-app-empty='true']");
+ if (emptyState != null) {
+ emptyState.style.display = visibleCount === 0 ? "block" : "none";
+ }
+ };
+
+ if (typeof document !== "undefined" && typeof window !== "undefined") {
+ window.requestAnimationFrame(() => {
+ const navigationItems = document.querySelector("#navigation-items");
+ if (navigationItems == null) {
+ return;
+ }
+
+ const sidebarHeaders = navigationItems.querySelectorAll(".sidebar-group-header");
+ const appsHeader = Array.from(sidebarHeaders).find((header) => header.textContent?.trim() === "Apps");
+ if (appsHeader == null) {
+ return;
+ }
+
+ const appsGroupContainer = appsHeader.parentElement;
+ const appsList = appsGroupContainer?.querySelector("ul");
+ if (appsGroupContainer == null || appsList == null) {
+ return;
+ }
+ const existingHeaderSearch = appsHeader.querySelector("[data-apps-sidebar-search='true']");
+ if (existingHeaderSearch != null) {
+ existingHeaderSearch.remove();
+ }
+ const legacySearchContainers = appsGroupContainer.querySelectorAll("div[data-apps-sidebar-search='true']");
+ for (const legacySearchContainer of legacySearchContainers) {
+ legacySearchContainer.remove();
+ }
+ const existingEmptyStates = appsGroupContainer.querySelectorAll("[data-apps-sidebar-empty='true']");
+ for (const existingEmptyState of existingEmptyStates) {
+ existingEmptyState.remove();
+ }
+
+ const searchInput = document.createElement("input");
+ searchInput.type = "text";
+ searchInput.placeholder = "Filter...";
+ searchInput.setAttribute("aria-label", "Filter apps in sidebar");
+ searchInput.style.width = "120px";
+ searchInput.style.height = "24px";
+ searchInput.style.borderRadius = "7px";
+ searchInput.style.padding = "0 8px";
+ searchInput.style.fontSize = "11px";
+ searchInput.style.lineHeight = "1";
+ searchInput.style.outline = "none";
+ searchInput.style.transition = "border-color 150ms ease, background-color 150ms ease, color 150ms ease";
+ searchInput.style.fontWeight = "500";
+ searchInput.style.marginLeft = "auto";
+ searchInput.style.flexShrink = "0";
+
+ const emptyState = document.createElement("div");
+ emptyState.setAttribute("data-apps-sidebar-empty", "true");
+ emptyState.style.display = "none";
+ emptyState.style.padding = "2px 0 8px 16px";
+ emptyState.style.fontSize = "12px";
+ emptyState.style.lineHeight = "1.3";
+
+ const emptyStatePrefix = document.createElement("span");
+ emptyStatePrefix.textContent = "No more results. ";
+ emptyState.appendChild(emptyStatePrefix);
+
+ const clearFilterButton = document.createElement("button");
+ clearFilterButton.type = "button";
+ clearFilterButton.textContent = "Clear filter";
+ clearFilterButton.style.border = "none";
+ clearFilterButton.style.padding = "0";
+ clearFilterButton.style.background = "transparent";
+ clearFilterButton.style.fontSize = "12px";
+ clearFilterButton.style.fontWeight = "600";
+ clearFilterButton.style.cursor = "pointer";
+ clearFilterButton.style.textDecoration = "underline";
+ clearFilterButton.style.textUnderlineOffset = "2px";
+ emptyState.appendChild(clearFilterButton);
+
+ const applyTheme = () => {
+ const isDark = document.documentElement.classList.contains("dark");
+ searchInput.style.background = isDark ? "rgba(17,24,39,0.72)" : "rgba(248,250,252,0.98)";
+ searchInput.style.color = isDark ? "#e5e7eb" : "#111827";
+ searchInput.style.border = isDark ? "1px solid rgba(75,85,99,0.9)" : "1px solid rgba(203,213,225,0.95)";
+ emptyState.style.color = isDark ? "rgba(203,213,225,0.86)" : "rgba(55,65,81,0.9)";
+ clearFilterButton.style.color = isDark ? "#8fb7ff" : "#295fbe";
+ };
+
+ const filterSidebarApps = () => {
+ const query = searchInput.value.trim().toLowerCase();
+ const appRows = Array.from(appsList.children);
+ let visibleCount = 0;
+ for (const row of appRows) {
+ const searchableElement = row.querySelector("a, button") ?? row;
+ const rowText = searchableElement.textContent?.replace(/\s+/g, " ").trim().toLowerCase() ?? "";
+ const isVisible = query.length === 0 || rowText.includes(query);
+ row.style.display = isVisible ? "" : "none";
+ if (isVisible) {
+ visibleCount += 1;
+ }
+ }
+ emptyState.style.display = query.length > 0 && visibleCount === 0 ? "block" : "none";
+ };
+
+ clearFilterButton.addEventListener("click", () => {
+ searchInput.value = "";
+ filterSidebarApps();
+ searchInput.focus();
+ });
+ searchInput.addEventListener("input", filterSidebarApps);
+ applyTheme();
+ const classObserver = new MutationObserver(applyTheme);
+ classObserver.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+
+ appsHeader.style.display = "flex";
+ appsHeader.style.alignItems = "center";
+ appsHeader.style.gap = "8px";
+ appsHeader.style.paddingRight = "12px";
+ searchInput.setAttribute("data-apps-sidebar-search", "true");
+ appsHeader.appendChild(searchInput);
+ appsGroupContainer.insertBefore(emptyState, appsList);
+ });
+ }
+
+ return (
+
+
+ );
+};
diff --git a/docs-mintlify/snippets/home-prompt-island.jsx b/docs-mintlify/snippets/home-prompt-island.jsx
new file mode 100644
index 000000000..943b460a7
--- /dev/null
+++ b/docs-mintlify/snippets/home-prompt-island.jsx
@@ -0,0 +1,66 @@
+export const HomePromptIsland = () => {
+ const agentSetupPromptPlaceholder = `You are my coding agent.
+
+Set up Stack Auth in this project.
+- Install and configure Stack Auth
+- Create initial authentication routes
+- Add sign-in and sign-up UI
+- Verify local development setup
+
+Return the exact files changed and next steps.`;
+
+ const onCopy = async (event) => {
+ const button = event.currentTarget;
+ await navigator.clipboard.writeText(agentSetupPromptPlaceholder);
+ button.textContent = "Copied";
+ window.setTimeout(() => {
+ button.textContent = "Copy prompt";
+ }, 1300);
+ };
+
+ return (
+
+
+
+
+ {appLinks.map((appLink) => (
+
+
+
+
+
+
+ {appLink.name}
+
+
+ ))}
+ + No apps match your search. +
+
+
+ );
+};
+ Agent-first setup +
+ ++ Start with a single prompt. +
++ Set up Stack Auth by copying the prompt below into your favorite coding agent. +
+ +
+
+
+
+
+
+
+