Backend SDK declarations fail with exactOptionalPropertyTypes and skipLibCheck=false
维护者通常 1 天内回复
@wobsoriano 已经在做这个了。
开始于 2026年9月28日。
评估
这个 Issue 还没有评估数据。
描述
Backend SDK declarations fail with exactOptionalPropertyTypes and skipLibCheck=false
Summary
Importing @clerk/backend 3.20.1 with @clerk/shared 4.36.0 produces eight TypeScript declaration errors with strict checking, exactOptionalPropertyTypes=true and skipLibCheck=false. The reproduction below uses no framework, provider account or credentials.
Environment: Windows x64, Node 24.15.0, npm 11.12.1, TypeScript 6.0.3. The SDK pair matches the latest stable npm tags checked on 2026-09-28.
Reproduction
Create these three files in an empty directory, then run npm install --ignore-scripts --no-audit and npm run check. A generated exact lockfile was used for the observed run.
package.json
{
"name": "clerk-strict-declaration-repro",
"version": "0.0.0",
"private": true,
"type": "module",
"engines": { "node": "24.15.0", "npm": "11.12.1" },
"scripts": { "check": "tsc --noEmit --pretty false" },
"dependencies": {
"@clerk/backend": "3.20.1",
"@clerk/shared": "4.36.0",
"react": "19.3.0",
"react-dom": "19.3.0"
},
"devDependencies": {
"@types/node": "24.19.0",
"@types/react": "19.3.0",
"@types/react-dom": "19.3.0",
"typescript": "6.0.3"
}
}
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"lib": ["dom", "dom.iterable", "esnext"],
"module": "esnext",
"moduleResolution": "bundler",
"strict": true,
"exactOptionalPropertyTypes": true,
"noUncheckedIndexedAccess": true,
"skipLibCheck": false,
"noEmit": true,
"esModuleInterop": true,
"jsx": "react-jsx"
},
"include": ["index.ts"]
}
index.ts
import { createClerkClient } from '@clerk/backend';
export type Client = ReturnType<typeof createClerkClient>;
// Compile only. No client is created and no credentials or network calls run.
export async function authenticate(client: Client, request: Request, origin: string) {
const state = await client.authenticateRequest(request, {
acceptsToken: 'session_token', authorizedParties: [origin],
});
const auth = state.toAuth();
if (!auth?.userId || !auth.sessionId || !auth.sessionClaims) return null;
const session = await client.sessions.getSession(auth.sessionId);
return {
issuer: auth.sessionClaims.iss, subject: auth.userId,
sessionId: session.id, status: session.status,
tokenExpiresAt: auth.sessionClaims.exp * 1000, expiresAt: session.expireAt,
};
}
Expected and observed
Expected: the public authentication/session types compile with full declaration checking. Observed: tsc exits 2 with two exact-optional class/interface errors, five missing optional modules and a missing appearance-registry theme.
> [email protected] check
> tsc --noEmit --pretty false
node_modules/@clerk/shared/dist/errors/clerkApiError.d.mts(7,15): error TS2420: Class 'ClerkAPIError<Meta>' incorrectly implements interface 'ClerkAPIError'.
Types of property 'longMessage' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.
node_modules/@clerk/shared/dist/errors/clerkApiResponseError.d.mts(16,3): error TS2416: Property 'errors' in type 'ClerkAPIResponseError' is not assignable to the same property in base type 'ClerkAPIResponseError'.
Type 'ClerkAPIError<any>[]' is not assignable to type 'ClerkAPIError[]'.
Type 'ClerkAPIError<any>' is not assignable to type 'ClerkAPIError' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
Types of property 'longMessage' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.
node_modules/@clerk/shared/dist/moduleManager.d.mts(3,36): error TS2307: Cannot find module '@zxcvbn-ts/core' or its corresponding type declarations.
node_modules/@clerk/shared/dist/moduleManager.d.mts(4,47): error TS2307: Cannot find module '@zxcvbn-ts/language-common' or its corresponding type declarations.
node_modules/@clerk/shared/dist/moduleManager.d.mts(5,38): error TS2307: Cannot find module '@base-org/account' or its corresponding type declarations.
node_modules/@clerk/shared/dist/moduleManager.d.mts(6,41): error TS2307: Cannot find module '@coinbase/wallet-sdk' or its corresponding type declarations.
node_modules/@clerk/shared/dist/moduleManager.d.mts(7,38): error TS2307: Cannot find module '@stripe/stripe-js' or its corresponding type declarations.
node_modules/@clerk/shared/dist/types/clerk.d.mts(48,53): error TS2339: Property 'theme' does not exist on type 'ClerkAppearanceRegistry'.
The class declares longMessage as string | undefined while its interface declares longMessage?: string. Those declarations conflict under exactOptionalPropertyTypes. Installing optional UI packages would not resolve that class/interface conflict.
Other tested versions
The same compiler flags and authentication/session consumer fail with these exact pairs. No dependency overrides or declaration patches were used.
| Backend | Shared | Result |
|---|---|---|
| 3.20.1 | 4.36.0 | 8 diagnostics |
| 2.33.7 | 3.48.0, types 4.101.27 | 32 diagnostics |
| 3.20.2-canary.v20260926175024 | 4.37.0-canary.v20260926175024 | 8 diagnostics |
| 2.33.3 | 3.47.5, types 4.101.23 | 32 diagnostics |
| 3.2.14 | 4.8.3 | 42 diagnostics |
The canary was tested only to check for an upcoming fix. The two older pairs are the first versions patched for GHSA-w24r-5266-9c3c. I found the older closed strict-types issue #326, but it concerns the former backend-core package and does not resolve this reproduction.
Is there a supported exact dependency pair or public entry point that retains authenticateRequest, sessionClaims and sessions.getSession types while passing these compiler settings? If not, can the published declarations be corrected without requiring skipLibCheck or application-side declaration shims?
- 主要语言
- TypeScript
- 星标
- 1.8k
- 派生
- 492
- 平均合并
- 1 天 8 小时
- 30 天内合并 PR
- 374
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
clerk/javascript 的其他 Issue
-
<SignIn />: the reset password code step renders an empty, focusable back button with no accessible name可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭
难度 2/5 1-3 小时 新手友好度 85/100
clerk/javascript#10708 ·
维护者通常 1 天内回复
-
Built-in reverification dialog lacks an accessible name (aria-dialog-name)可能已有人在做 @ItsShivam05 于 5 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 75/100
clerk/javascript#10548 ·
维护者通常 1 天内回复
-
MFA enrollment QR SVG lacks an accessible name (svg-img-alt)可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭
难度 2/5 1-3 小时 新手友好度 84/100
clerk/javascript#10547 ·
维护者通常 1 天内回复
-
<SignIn />: first "Use email" click switches back to phone when `initialValues.phoneNumber` is set可能已有人在做 @twicestruck 于 22 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 74/100
clerk/javascript#10487 ·
维护者通常 1 天内回复
-
useLoadedIsomorphicClerk misses "ready" when a ClerkProvider remounts after clerk-js has loaded — <ClerkLoading> never resolves可能重新可做 关联的 PR 已关闭且未合并。 未关闭
难度 2/5 1-3 小时 新手友好度 82/100
clerk/javascript#10462 ·
维护者通常 1 天内回复
相似的 Issue
-
`@angular/[email protected]` depends on vulnerable Vite 7.3.7 - GHSA-p4f5-76q4-ffq7 (Critical RCE)未关闭area: @angular/build
难度 2/5 1-3 小时 新手友好度 65/100
angular/angular-cli#34764 ·
维护者通常 1 天内回复
-
status/need-triage
难度 2/5 1-3 小时 新手友好度 76/100
google-gemini/gemini-cli#30384 · 1 条评论 ·
维护者通常 1 天内回复
-
P2
难度 1/5 1 小时以内 新手友好度 84/100
维护者通常 1 天内回复
-
bug ready-for-human
难度 2/5 1-3 小时 新手友好度 60/100
LucasSantana-Dev/Lucky#3150 ·
维护者通常 1 天内回复
-
enhancement good first issue priority: low size: XS
难度 2/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复