[Nicolapps]

The broken httpCookies example fixed in #734 got through CI because tsc doesn't read code in doc comments, and nothing else checked it. TypeDoc copies these examples into the API reference and the shipped .d.ts.

This adds pnpm check:doc-examples (scripts/checkDocExamples.ts) and runs it in the TypeScript workflow after pnpm build. The script finds every ```ts / ```tsx block in a /** */ comment under packages/core/src and typechecks each one as a module of a sample app.

The sample app: packages/doc-examples

A private Convex app (not an example to copy) that installs every component and sets up every sign-in method in one convex/auth.ts, including a generic setupOauth provider ("acme"). Its _generated/ is committed, and the existing codegen workflow keeps it up to date. A Next-style root auth.ts with setupConvexAuthServer is reachable as @/auth.

Thus api, internal, components, env and ctx in the examples have their real generated types, not any.

How an example is checked

• tsx examples go in the app's src/, examples from ssr/ go in app/, and the rest go in convex/, so ../convex/_generated/api, ./_generated/server and @/auth resolve to real files. The app's tsconfig.json is used.
• If an example uses a name it doesn't import, the script adds an import from the first module that exports it: the commented file's own entry point of @convex-dev/auth, the other entry points, react, convex/*, the app's _generated/api and _generated/server, and then the commented file itself.
• A small prelude declares ctx (the app's QueryCtx), app (its convex.config.ts), the component definitions, react-router's Navigate, and expo-secure-store.
• ```ts skip-check opts a block out. It's used once, for the internal buildCallbackRouter example, which refers to names of a component.

With the old httpCookies example put back, the check reports the unknown authApi option and the RefreshResult being passed as a token bundle. Putting api.auth.startSignInAcmee, env.RESEND_KEY, or components.authPassword (in place of authGoogle) into an example also makes it fail.

Examples fixed

The examples that the check found broken are fixed in the PRs below this one, one PR per fix: #767, #768, #769, #770, #771, #772, #773.

The script also runs in preversion, and AGENTS.md describes it and the sample app.

A finding

setupOauth takes the user callbacks as a direct argument, not through attachUserCallbacks. As a result, passing internal.users.createUserAcme from a module that is part of api fails with TS7022 (the type of api depends on itself). The sample app works around it with makeFunctionReference. Apps that use the generic OAuth method would hit the same error.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
auth-v2	Ready	Preview	Oct 21, 2026 1:31am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
convex-auth-docs	Ignored		Oct 21, 2026 1:31am UTC

[Nicolapps]

• Typecheck doc examples against a sample app #764
• Typecheck the code examples in doc comments in CI #763 👈 (View in Graphite)
• Fix the useSignInWithUsernamePasskey example #769
• Set pending while an autofill passkey sign-in is verified #774
• Import auth in the SSR sign-in route examples #773
• Declare auth in the Google, Apple and GitHub setup examples #772
• Fix the env import in the setupEmailPassword example #771
• Declare emailCode in the useCompleteSignUp example #770
• reboot

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cubic-dev-ai]

1 issue found across 11 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/checkDocExamples.ts">

<violation number="1" location="scripts/checkDocExamples.ts:308">
P2: Diagnostics for the prelude and stubs are never collected. `getPreEmitDiagnostics(program, sourceFile)` only returns errors for that example file, so a broken `PRELUDE` type silently degrades to `any`. Also collect `getPreEmitDiagnostics` for `prelude.d.ts` and the stub files and report them as errors.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Diagnostics for the prelude and stubs are never collected. getPreEmitDiagnostics(program, sourceFile) only returns errors for that example file, so a broken PRELUDE type silently degrades to any. Also collect getPreEmitDiagnostics for prelude.d.ts and the stub files and report them as errors.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/checkDocExamples.ts, line 308:

<comment>Diagnostics for the prelude and stubs are never collected. `getPreEmitDiagnostics(program, sourceFile)` only returns errors for that example file, so a broken `PRELUDE` type silently degrades to `any`. Also collect `getPreEmitDiagnostics` for `prelude.d.ts` and the stub files and report them as errors.</comment>

<file context>
@@ -0,0 +1,360 @@
+  return new Map(
+    examples.map((e) => [
+      e,
+      ts.getPreEmitDiagnostics(program, program.getSourceFile(e.path)),
+    ]),
+  );
</file context>

[cubic-dev-ai]

No issues found across 11 files

_{Re-trigger cubic}

[pkg-pr-new]

npm i https://pkg.pr.new/@convex-dev/auth@763

commit: c246f43