[Docs Mintlify] - Updates and new additions#1401
Open
madster456 wants to merge 3 commits intodevfrom
Open
Conversation
… known-errors, and revamped self-host
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughDocumentation and user interface expansion for Stack Auth. Navigation configuration updated to route three new guides. Comprehensive guides for CLI usage, local emulator operation, and local development added. Existing guides for self-hosting, authentication, and JWT handling revised. Showcase page and supporting CSS styling implemented. ChangesDocumentation and UI Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR adds several new documentation pages to the Mintlify docs site — a Stack CLI reference, a local emulator guide, a known-errors reference, and a fully rewritten self-host guide — while expanding the previously stub-only local-development page and populating the showcase page. Non-doc changes are minimal: a trivial import-order swap in
Confidence Score: 4/5Safe to merge; the only real concern is an orphaned archive file unreachable from nav that could surface in search. All findings are P2. The orphaned self-host-old.mdx carries no runtime risk. Code changes are trivial. docs-mintlify/guides/other/self-host-old.mdx — confirm whether this should be deleted or intentionally kept out of navigation Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
GF["Going Further"]
GF --> CLI["cli.mdx\n(Stack CLI reference)"]
GF --> LE["local-emulator.mdx\n(QEMU emulator guide)"]
GF --> LD["local-development.mdx\n(cloud-backed & emulator workflows)"]
CLI -->|links to| LE
LD -->|links to| LE
LD -->|links to| CLI
Other["Other"]
Other --> SH["self-host.mdx\n(revamped Docker deploy)"]
Other --> KE["known-errors.mdx\n(new SDK error reference)"]
Other --> OLD["self-host-old.mdx\n(orphaned archive ⚠️)"]
SH -.->|content moved from| OLD
Prompt To Fix All With AIFix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
docs-mintlify/guides/other/self-host-old.mdx:1-5
**Orphaned archive file not linked in navigation**
`self-host-old.mdx` is not referenced in `docs.json`, so it is unreachable from the docs nav. It contains the old local-development setup section that now contradicts the new guides (it still tells contributors to clone the repo and run `pnpm run dev` as a local dev workflow). If this is intentional archival, consider removing it entirely; otherwise search engines may surface it as conflicting documentation.
### Issue 2 of 2
docs-mintlify/guides/apps/authentication/jwts.mdx:17-20
**Leftover blank line after JWT viewer removal**
Removing the "JWT Viewer" section left two consecutive blank lines between the `header.payload.signature` paragraph and the `## Stack Auth JWT Structure` heading. Consider removing the extra blank line for cleaner rendering.
Reviews (1): Last reviewed commit: "Updates to jwts, setup. Added cli, local..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-mintlify/guides/apps/authentication/jwts.mdx`:
- Line 264: Insert a clear security warning immediately before the sentence "Use
a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify
their contents." advising readers to never paste live production tokens into
external sites and to use only redacted/test tokens; also add a local-decoding
alternative suggestion (e.g., jwt-cli, built-in language libraries, or browser
devtools) and a short example phrase like "prefer local decoding or redaction"
to steer users away from exposing secrets.
In `@docs-mintlify/guides/going-further/local-development.mdx`:
- Line 96: Replace the phrase "config-file backed development" with the
hyphenated compound modifier "config-file-backed development" in the sentence
that currently reads "If you use config-file backed development,
`stack.config.ts` becomes the local source of truth for Stack Auth settings." to
improve readability.
In `@docs-mintlify/guides/other/self-host-old.mdx`:
- Line 39: Fix the grammar in the sentence that reads "Use a cloud hosted
Postgres or start a example Postgres database. Don't use this setting in
production:" by changing "a example" to "an example" so it reads "Use a cloud
hosted Postgres or start an example Postgres database. Don't use this setting in
production:"; update the string exactly where it appears in
docs-mintlify/guides/other/self-host-old.mdx.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9f5a9351-848c-4a94-b072-f7f20a1ad34c
⛔ Files ignored due to path filters (3)
docs-mintlify/images/showcase/browser-use.pngis excluded by!**/*.pngdocs-mintlify/images/showcase/over.world.pngis excluded by!**/*.pngpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (14)
docs-mintlify/docs.jsondocs-mintlify/guides/apps/authentication/cli-authentication.mdxdocs-mintlify/guides/apps/authentication/jwts.mdxdocs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/guides/going-further/cli.mdxdocs-mintlify/guides/going-further/local-development.mdxdocs-mintlify/guides/going-further/local-emulator.mdxdocs-mintlify/guides/other/known-errors.mdxdocs-mintlify/guides/other/self-host-old.mdxdocs-mintlify/guides/other/self-host.mdxdocs-mintlify/guides/other/showcase.mdxdocs-mintlify/style.csspackage.jsonpackages/stack-cli/src/commands/emulator.ts
💤 Files with no reviewable changes (1)
- docs-mintlify/guides/getting-started/setup.mdx
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-mintlify/guides/going-further/local-emulator.mdx`:
- Line 7: The intro sentence uses an un-hyphenated compound modifier
"config-file backed projects"; update the sentence in the local emulator intro
(the line starting "The Stack Auth local emulator runs the Stack Auth
dashboard...") to use the hyphenated compound adjective "config-file-backed
projects" so it reads "...config-file-backed projects, or an isolated Stack Auth
environment for testing."
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 36e382e2-9116-4e85-9079-a723d12ea558
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (2)
docs-mintlify/guides/going-further/local-emulator.mdxpackage.json
✅ Files skipped from review due to trivial changes (1)
- package.json
Collaborator
Author
|
Added a root Without the override, Mintlify pulls an older |
mantrakp04
approved these changes
May 1, 2026
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-mintlify/guides/going-further/local-emulator.mdx`:
- Line 186: The exported token line uses angle brackets which the shell treats
as input redirection; update the export of GITHUB_TOKEN to use a literal,
shell-safe placeholder (e.g., a quoted placeholder string) instead of `<token>`
so the shell won't interpret it as a redirection when running the line with the
GITHUB_TOKEN variable.
In `@docs-mintlify/guides/other/self-host.mdx`:
- Line 71: Replace the future ClickHouse image tag string
"clickhouse/clickhouse-server:25.10" with a currently published tag (for example
"clickhouse/clickhouse-server:25.8" or "clickhouse/clickhouse-server:latest") in
the docs-mintlify/guides/other/self-host.mdx content so the smoke-test Docker
pull succeeds; update the single line containing the exact token
clickhouse/clickhouse-server:25.10 to the chosen published tag.
- Around line 162-173: Add a short clarifying note near the scheduler curl
examples explaining that the `/api/latest/internal/...` endpoints (e.g.,
`/api/latest/internal/email-queue-step`,
`/api/latest/internal/external-db-sync/sequencer`,
`/api/latest/internal/external-db-sync/poller`) are internal operational
endpoints intended for cron/devops use and may change with deploys, whereas
`/api/v1/internal/...` (e.g., `/api/v1/internal/backend-urls`) is a versioned
API namespace used for stable public/internal API contracts; update the text to
state they are not interchangeable and to use `/api/latest/internal/` for
scheduled operational tasks and `/api/v1/` for versioned API calls.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8e73e411-ed49-4067-8cb8-aec80a9a16f7
📒 Files selected for processing (2)
docs-mintlify/guides/going-further/local-emulator.mdxdocs-mintlify/guides/other/self-host.mdx
| ```sh title="Terminal" | ||
| gh auth login | ||
| # or | ||
| export GITHUB_TOKEN=<token> |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs-mintlify/guides/going-further/local-emulator.mdx | sed -n '180,195p'Repository: hexclave/stack-auth
Length of output: 973
🏁 Script executed:
#!/bin/bash
# Test 1: Try to run the exact command and see what happens
echo "Test 1: Shell interpretation of the problematic syntax"
bash -n -c 'export GITHUB_TOKEN=<token>' 2>&1
echo "Exit code: $?"
# Test 2: Show what the shell parser sees
echo -e "\nTest 2: Checking if < is treated as redirection"
bash -n -c 'export GITHUB_TOKEN=<nonexistent_file_xyz>' 2>&1
echo "Exit code: $?"
# Test 3: Compare with quoted version
echo -e "\nTest 3: Shell interpretation of the quoted version"
bash -n -c 'export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"' 2>&1
echo "Exit code: $?"
# Test 4: Check if a user might accidentally create/use a file
echo -e "\nTest 4: What happens when 'token' file exists"
mkdir -p /tmp/shell_test
echo "some_token_content" > /tmp/shell_test/token
cd /tmp/shell_test
bash -n -c 'export GITHUB_TOKEN=<token>' 2>&1
echo "Exit code: $?"Repository: hexclave/stack-auth
Length of output: 666
Replace placeholder with shell-safe literal string.
On line 186, export GITHUB_TOKEN=<token> is interpreted by the shell as input redirection syntax (the < operator), causing a syntax error when copy-pasted. Use a literal placeholder string instead:
Suggested fix
-export GITHUB_TOKEN=<token>
+export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export GITHUB_TOKEN=<token> | |
| export GITHUB_TOKEN="YOUR_GITHUB_TOKEN" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs-mintlify/guides/going-further/local-emulator.mdx` at line 186, The
exported token line uses angle brackets which the shell treats as input
redirection; update the export of GITHUB_TOKEN to use a literal, shell-safe
placeholder (e.g., a quoted placeholder string) instead of `<token>` so the
shell won't interpret it as a redirection when running the line with the
GITHUB_TOKEN variable.
| -e CLICKHOUSE_PASSWORD=password \ | ||
| -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \ | ||
| -p 8123:8123 \ | ||
| clickhouse/clickhouse-server:25.10 |
Contributor
There was a problem hiding this comment.
clickhouse/clickhouse-server:25.10 is a future image tag and will fail to pull
The most recent ClickHouse Docker image tags listed on Docker Hub are 25.8 and its variants. Tag 25.10 (October 2025, using ClickHouse's YY.MM calendar versioning) has not been released yet as of May 2026, so docker pull clickhouse/clickhouse-server:25.10 will fail for anyone following this smoke-test guide today. Replace it with a currently published tag such as 25.8 or latest.
📝 Proposed fix
- clickhouse/clickhouse-server:25.10
+ clickhouse/clickhouse-server:25.8🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs-mintlify/guides/other/self-host.mdx` at line 71, Replace the future
ClickHouse image tag string "clickhouse/clickhouse-server:25.10" with a
currently published tag (for example "clickhouse/clickhouse-server:25.8" or
"clickhouse/clickhouse-server:latest") in the
docs-mintlify/guides/other/self-host.mdx content so the smoke-test Docker pull
succeeds; update the single line containing the exact token
clickhouse/clickhouse-server:25.10 to the chosen published tag.
Comment on lines
+162
to
+173
| | Endpoint | Purpose | | ||
| | --- | --- | | ||
| | `/api/latest/internal/email-queue-step` | Processes queued emails. | | ||
| | `/api/latest/internal/external-db-sync/sequencer` | Schedules external database sync work. | | ||
| | `/api/latest/internal/external-db-sync/poller` | Polls and advances external database sync work. | | ||
|
|
||
| For example, a scheduler can run these requests every minute: | ||
|
|
||
| ```bash title="Scheduler" | ||
| curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/email-queue-step | ||
| curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/external-db-sync/sequencer | ||
| curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/external-db-sync/poller |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check usage of /api/latest/internal vs /api/v1/internal across the repo
rg -n "api/latest/internal|api/v1/internal" --type md --type mdx -g "*.mdx" -A1 -B1Repository: hexclave/stack-auth
Length of output: 91
🏁 Script executed:
#!/bin/bash
# Search for both API paths without file type restrictions
echo "=== Searching for /api/latest/internal and /api/v1/internal ==="
rg -n "api/latest/internal|api/v1/internal" -A1 -B1 | head -100Repository: hexclave/stack-auth
Length of output: 9582
🏁 Script executed:
#!/bin/bash
# Search for API route definitions in the server code
echo "=== Looking for route handlers in server implementation ==="
fd -e ts -e tsx -e js -e jsx | xargs grep -l "api/v1/internal\|api/latest/internal" 2>/dev/null | head -20Repository: hexclave/stack-auth
Length of output: 1263
🏁 Script executed:
#!/bin/bash
# Check the self-host.mdx file directly for the specific lines mentioned
echo "=== Checking lines around 171-173 and 284 in self-host.mdx ==="
wc -l docs-mintlify/guides/other/self-host.mdxRepository: hexclave/stack-auth
Length of output: 171
Clarify the purpose of /api/latest/internal/ vs /api/v1/internal/ endpoints
The cron scheduler examples use /api/latest/internal/... paths (lines 164-166, 171-173), while the health-check command uses /api/v1/internal/backend-urls (line 284). The codebase consistently uses both paths for different purposes — /api/latest/internal/ for internal operational endpoints (cron jobs, dev tools) and /api/v1/ for versioned public API endpoints. Add a brief note explaining this distinction so operators understand they are not interchangeable and each is correct for its intended use.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs-mintlify/guides/other/self-host.mdx` around lines 162 - 173, Add a short
clarifying note near the scheduler curl examples explaining that the
`/api/latest/internal/...` endpoints (e.g.,
`/api/latest/internal/email-queue-step`,
`/api/latest/internal/external-db-sync/sequencer`,
`/api/latest/internal/external-db-sync/poller`) are internal operational
endpoints intended for cron/devops use and may change with deploys, whereas
`/api/v1/internal/...` (e.g., `/api/v1/internal/backend-urls`) is a versioned
API namespace used for stable public/internal API contracts; update the text to
state they are not interchangeable and to use `/api/latest/internal/` for
scheduled operational tasks and `/api/v1/` for versioned API calls.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refreshes the docs around Stack Auth setup, CLI workflows, local development, the local emulator, known SDK errors, self-hosting, and the public showcase. This also wires the new docs into Mintlify navigation and normalizes
sharpdependency resolution for docs/image tooling.Base:
dev-> Head:docs-mintlify/updatesScope: 17 files, +1154 / -435
What's New
stack exec, and emulator commands.stackauth/serverDocker deployment path, including Postgres, ClickHouse, cron scheduling, seeded admin access, reverse proxy setup, SDK env vars, email, webhooks, S3 storage, upgrades, and common issues.errorCodevalues, and REST API handling.stackcommand.sharpto0.34.5through pnpm overrides and lockfile cleanup.Review Notes
self-host-old.mdxis kept as a legacy reference file and is not added to navigation.emulator rundocumentation now matches CLI behavior: it stops the emulator only when it started that emulator instance.Test Plan
origin/dev...HEAD.git diff --check origin/dev...HEAD.Summary by CodeRabbit
Documentation
Style