[Docs Mintlify] - Updates and new additions#1401
Conversation
… known-errors, and revamped self-host
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughAdds and updates multiple documentation pages: new CLI, local emulator, known errors, self-hosting, local development, and showcase guides; modifies docs navigation and styling; minor package.json override and a trivial import reordering in the CLI source. No runtime code or public API changes. Changes
Sequence Diagram(s)(Skipped — changes are documentation, styling, and small import/config edits; no new runtime control flow introduced.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Suggested reviewers
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. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
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}
| --- | ||
| title: Self-host | ||
| description: Deploy Stack Auth on your own infrastructure with full control over your authentication system. | ||
| --- | ||
|
|
There was a problem hiding this comment.
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.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs-mintlify/guides/other/self-host-old.mdx
Line: 1-5
Comment:
**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.
How can I resolve this? If you propose a fix, please make it concise.|
|
||
| The structure looks like this: `header.payload.signature` | ||
|
|
||
| ## JWT Viewer | ||
|
|
||
| Use the interactive JWT viewer below to decode and inspect JWT tokens. If you're signed in, it will automatically load and display your current session token: | ||
|
|
There was a problem hiding this comment.
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.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs-mintlify/guides/apps/authentication/jwts.mdx
Line: 17-20
Comment:
**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.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
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
| ### Debugging JWTs | ||
|
|
||
| Use the JWT viewer above to inspect tokens and verify their contents. Pay special attention to: | ||
| Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. Pay special attention to: |
There was a problem hiding this comment.
Add a warning before recommending third-party JWT viewers.
Pointing to jwt.io without a caution may lead users to paste active production tokens into an external site. Add an explicit “use only redacted/test tokens” warning and suggest local decoding where possible.
🔐 Proposed doc tweak
-Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. Pay special attention to:
+Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents.
+Never paste active production tokens into third-party tools; use test/redacted tokens (or a local decoder) instead. Pay special attention to:📝 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.
| Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. Pay special attention to: | |
| Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. | |
| Never paste active production tokens into third-party tools; use test/redacted tokens (or a local decoder) instead. Pay special attention to: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs-mintlify/guides/apps/authentication/jwts.mdx` at 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.
|
|
||
| ## Local config files | ||
|
|
||
| If you use config-file backed development, `stack.config.ts` becomes the local source of truth for Stack Auth settings. The emulator reads that file and creates or updates a matching local project. |
There was a problem hiding this comment.
Hyphenate the compound modifier for readability.
Use config-file-backed development instead of config-file backed development.
✏️ Proposed text fix
-If you use config-file backed development, `stack.config.ts` becomes the local source of truth for Stack Auth settings.
+If you use config-file-backed development, `stack.config.ts` becomes the local source of truth for Stack Auth settings.📝 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.
| If you use config-file backed development, `stack.config.ts` becomes the local source of truth for Stack Auth settings. The emulator reads that file and creates or updates a matching local project. | |
| If you use config-file-backed development, `stack.config.ts` becomes the local source of truth for Stack Auth settings. The emulator reads that file and creates or updates a matching local project. |
🧰 Tools
🪛 LanguageTool
[grammar] ~96-~96: Use a hyphen to join words.
Context: ...cal config files If you use config-file backed development, stack.config.ts be...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs-mintlify/guides/going-further/local-development.mdx` at 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.
|
|
||
| Stack Auth provides a [pre-configured Docker](https://hub.docker.com/r/stackauth/server) image that bundles the dashboard and API backend into a single container. To complete the setup, you'll need to provide your own PostgreSQL database, and optionally configure an email server and Svix instance for webhooks. | ||
|
|
||
| 1. Use a cloud hosted Postgres or start a example Postgres database. Don't use this setting in production: |
There was a problem hiding this comment.
Fix grammar error: "a example" → "an example".
-1. Use a cloud hosted Postgres or start a example Postgres database. Don't use this setting in production:
+1. Use a cloud-hosted Postgres or start an example Postgres database. Don't use this setting in production:📝 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.
| 1. Use a cloud hosted Postgres or start a example Postgres database. Don't use this setting in production: | |
| 1. Use a cloud-hosted Postgres or start an example Postgres database. Don't use this setting in production: |
🧰 Tools
🪛 LanguageTool
[grammar] ~39-~39: Use a hyphen to join words.
Context: ...x instance for webhooks. 1. Use a cloud hosted Postgres or start a example Postg...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs-mintlify/guides/other/self-host-old.mdx` at 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.
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
| sidebarTitle: "Local Emulator" | ||
| --- | ||
|
|
||
| The Stack Auth local emulator runs the Stack Auth dashboard, backend, and supporting services on your machine. It is useful when you want local-first development, config-file backed projects, or an isolated Stack Auth environment for testing. |
There was a problem hiding this comment.
Fix compound modifier hyphenation in the intro sentence.
Line 7 should use a hyphenated compound adjective: config-file-backed projects.
🧰 Tools
🪛 LanguageTool
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...ant local-first development, config-file backed projects, or an isolated Stack Au...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs-mintlify/guides/going-further/local-emulator.mdx` at 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."
|
Added a root Without the override, Mintlify pulls an older |
| STACK_DATABASE_CONNECTION_STRING=postgresql://postgres:password@stack-auth-postgres:5432/stackframe | ||
| STACK_SERVER_SECRET=replace-with-a-32-byte-base64url-secret | ||
| CRON_SECRET=replace-with-a-long-random-secret | ||
|
|
There was a problem hiding this comment.
Bug: The smoke-test ClickHouse container above creates CLICKHOUSE_DB=analytics, but this env block never sets STACK_CLICKHOUSE_DATABASE=analytics. As far as I can tell the backend will target its default database instead of the one the example created.
| - `lsof` | ||
| - `openssl` | ||
|
|
||
| `zstd` is optional but recommended for compressed snapshot handling. |
There was a problem hiding this comment.
zstd does not seem optional for the default fresh-start path. emulator start captures a snapshot, and the capture path calls zstd, so a user following this without installing it can fail instead of just losing compressed snapshot handling.
| @@ -0,0 +1,168 @@ | |||
| --- | |||
There was a problem hiding this comment.
accident? this adds an orphan copy of the old self-host docs that is not in docs.json, and it still contains stale local-development/build instructions. I think we should delete it unless this is intentionally linked by some archive/redirect flow.
There was a problem hiding this comment.
Was left for archival purposes, my intention was to remove before merge. Just mental reference while building out the new one.
2 participants
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