refactor(core-web): TS strict mode across utils-testing, utils, dotcms-js, sdk-create-app + webcomponents groundwork

[nicobytes]

What

Six steps of the strict-mode rollout (epic #35932), plus groundwork on a seventh:

Issue	Project	Change
#35945	sdk-react	Enable the 5 missing flags + fix 14 TS4111 index-signature accesses
#35944	utils-testing	Strict was declared but inert — a stale types: ["jasmine"] aborted all type checking
#35940	utils	Enable strict + fix the 32 (+17 spec) resulting type errors
#35939	dotcms-js	Enable strict + fix the 38 resulting type errors
#35938	sdk-create-app	Enable strict + fix the 2 resulting type errors
#35935	sdk-types	No code needed — it was already strict. Documents the rollout pattern instead.

All three add the standard six flags to the project's own tsconfig.json, following the pattern established in #36879 (dotcms-models). tsconfig.base.json stays at "strict": false — the rollout never flips it globally.

---

dotcms-js (#35939)

The largest of the three: 38 errors across 11 files, in a layer-1 core library with 20 dependent projects, including the dotcms-ui admin app. Six of those dependents are already strict, so this library's loose types were leaking uncertainty into projects that had opted into rigour.

Most fixes correct types that were simply wrong, rather than silencing the compiler:

Site	Was	Reality
Auth.loginAsUser	User	The code has always passed null when nobody is impersonating, and every consumer already guards with auth.loginAsUser || auth.user. Now User | null.
StringUtils.getLine	string	Its own JSDoc says "null if it does not exists". Now string | null.
HttpRequestUtils.getQueryStringParam	string	Same — JSDoc already documented the null case.
RoutingService.getPortletURL	string	Returns Map.get(). Now string | undefined.
SiteService.switchSiteById	Observable<Site>	Emits of(null) when no site is found. Now Observable<Site | null>; its one consumer already handled null.
ResponseView.bodyJsonObject	DotCMSResponse<T>	Assigned from HttpResponse.body, which is nullable. The surrounding try/catch could never throw and has been removed.

LoginService.urls moved from Record<string, string> to inference-typed, which resolves all 8 TS4111 errors at once and gives each endpoint a named property.

Two definite-assignment assertions were used, each with a TODO: LoginService._auth and SiteService.selectedSite are assigned during init but not in the constructor. Modelling them as | undefined is the truthful type, but their public getters (auth, currentSite) are consumed by already-strict projects, so widening them is a public-API change that belongs in its own issue.

No new any, @ts-ignore, or @ts-expect-error anywhere in this PR.

⚠️ dotcms-js has no build target and is tag-excluded from lint and test, so nothing in CI verifies these flags. They document intent; they do not enforce it. This was an explicit scoping decision — no typecheck target or CI gate was added. The six already-strict consumers provide partial, incidental coverage only. Full reasoning in specs/35939-dotcms-js-strict-mode/spec.md, which is included in this PR.

Blast-radius verification

data-access (a strict consumer) went from 106 type errors to 68, with zero new errors introduced — the honest types upstream remove noise downstream. dotcms-ui typechecks clean apart from a pre-existing missing dotcms-webcomponents/loader dist.

---

utils (#35940)

32 errors across only 3 files, plus 17 more that appeared in the spec files once the flags propagated through tsconfig.spec.json (baseline there was 0). Both are fixed here — leaving the spec errors would have shipped a regression.

The bulk was one constant. EMPTY_FIELD assigned null to 18 members that DotCMSContentTypeField declares non-nullable:

• Replaced with zero values of the declared types. Verified safe: nothing compares those members to null strictly — consumers use falsy checks such as isNewField's !field.id — so '', 0 and false behave identically at runtime.
• clazz has no zero value (DotCMSClazz is a union of concrete Java class names), so EMPTY_FIELD and EMPTY_SYSTEM_FIELD are now Omit<DotCMSContentTypeField, 'clazz'>. They are partial templates, not valid fields, and the type now says so. The derived COLUMN_FIELD / ROW_FIELD / TAB_FIELD already supply their own clazz, so they remain complete.

Other fixes:

Site	Change
getFieldsWithoutLayout	Truthy .filter() did not narrow the optional row.columns. A type predicate clears the TS2532 and both TS2769 without a cast.
ellipsizeText	Accepted null/undefined at runtime — its own guard and its tests say so — but declared string/number. Widened to match, with an explicit limit == null check so later comparisons narrow.
fallbackErrorMessages	Typed { [key: number]: string }, mirroring the identical declaration already in libs/data-access/.../dot-upload.service.ts.
dot-utils.ts	Bracket access for the six DotCMSContentlet index-signature reads in getImageAssetUrl.
dot-asset.service.ts	Explicit types for promises and the two fetchAsset params.

The nine as unknown as casts added are all in spec files, on inputs the tests deliberately pass as invalid, matching the idiom those files already used.

⚠️ Same enforcement gap as dotcms-js: utils has no build target and is tag-excluded from lint and test, so nothing in CI verifies these flags. Accepted trade-off, consistent with #35939.

Blast-radius verification

data-access (strict consumer) went from 68 type errors to 36, zero new. utils-testing (strict) unchanged at its 1 pre-existing error — the Omit did not break its EMPTY_SYSTEM_FIELD spread.

---

sdk-create-app (#35938)

Two errors, both from flags beyond plain strict:

• src/index.ts:393 — process.env.DEBUG needs bracket access under noPropertyAccessFromIndexSignature (TS4111). It is the only process.env.* dot access in the project.
• src/utils/index.ts:41 — fetchWithRetry tripped noImplicitReturns (TS7030). The loop returns on success and throws on the last attempt, but with retries < 1 the loop never runs and the function fell through returning undefined. Its only caller (isDotcmsRunning, src/index.ts:506) already guarded with if (res && …), so nothing broke in practice — but the signature was lying. Throwing after the loop closes the gap and narrows the return type to Promise<AxiosResponse>.

No build or CI wiring was needed here. The @nx/esbuild:esbuild executor type-checks before bundling (skipTypeCheck defaults to false and is not overridden), and CI already builds this project via nx run-many -t build (build-test in core-web/pom.xml). The same build runs in the SDK release pipeline (cicd_release-sdk.yml → nx run-many --projects='sdk-*'), so the flags are enforced on every release.

---

sdk-types (#35935)

libs/sdk/types/tsconfig.json has carried strict: true plus the four extra safety flags since the library was created (#31967), and tsc --noEmit passes with zero errors. It is also already enforced: tsconfig.lib.json sets "declaration": true, so @rollup/plugin-typescript sits in the Rollup chain and fails the build on a strict violation.

So no code change was required. What was missing was documentation, added here to core-web/CLAUDE.md:

• A ## TypeScript Strict Mode section covering the per-project flags, what actually enforces them, and the Vite exception (esbuild skips type checking, which is why the Nx Vite plugin infers a separate typecheck target).
• Fixes a line that forbade "strict": true in project tsconfigs. It sat under the Jest config guidance but read as a blanket ban, contradicted docs/frontend/TYPESCRIPT_STANDARDS.md, and blocked the epic outright. The restriction now points at tsconfig.spec.json, which is what it meant.

---

---

utils-testing (#35944)

The six strict flags were already in tsconfig.json — but completely inert. tsconfig.lib.json declared "types": ["jasmine"], that package is not installed, so tsc emitted TS2688: Cannot find type definition file for 'jasmine' and stopped before semantic checking. The project reported exactly one error regardless of what the code did.

The reference was stale: nothing uses jasmine, two files use jest.*, and @types/jest is installed. Switching to "types": ["jest"] removed the abort and 27 spurious Cannot find name 'jest' errors, leaving 5 real ones:

Site	Fix
clean-up-dialog.ts	Untyped fixture param → typed structurally as { nativeElement: unknown }, since only that property is touched (no need to pull in Angular's ComponentFixture)
dot-page-state.service.mock.ts	_lock: boolean = null → boolean | null
dot-page-tools.mock.ts ×3	Mock entries carried a tags array that DotPageTool does not declare. Verified nothing in the repo reads .tags off a page tool, so the dead field was removed rather than added to the model in dotcms-models

tsc -p libs/utils-testing/tsconfig.lib.json --noEmit now exits 0 with no CLI overrides — the check is real rather than short-circuited.

Verified across consumers of the touched mocks (cleanUpDialog in 7 files, page-tools mock in 3): data-access 751 tests passed, edit-ema-ui 338 passed.

---

dotcms-webcomponents (#35943) — groundwork only, not closed

Strict is not enabled here. ~250 errors remain across 38 files, and unlike the other projects this one has no skip:build, so Stencil type-checks it on every PR — flipping the flag early turns CI red. What landed is the part that is correct on its own.

The decorator split, which is the load-bearing decision. Stencil declares runtime-injected members without initializers, colliding with strictPropertyInitialization (139 of the original 375 errors). The fix cannot be uniform:

Decorator	Count	Fix	Why
@Event	57	!	Internal; the runtime creates the EventEmitter
@Element	27	!	Internal; the host element
@State	25	!	Internal component state
@Prop	30	?	Public API

Using ! on @Prop made Stencil emit 28 props as required in components.d.ts — breaking for any TS/JSX consumer. With ? the generated API moves required → optional, which is backward compatible. Measured in the generated file, not assumed.

Two traps recorded on the issue

Stencil under-reports. Its build shows ~10 files / ~39 errors per run, not the total. Measured at the same commit: Stencil 39 errors / 10 files vs tsc 250 / 38. Size this work with tsc, not with build output.

--skip-nx-cache does not clear Stencil's cache. Builds can report green against stale .stencil output. This bit me: 0117273504 annotated a prop, passed a "clean" build, and was actually broken — reverted in f22afce383 after verifying twice with .stencil and the Nx cache cleared.

That prop (dot-binary-text-field's value) is genuinely contradictory: handleFilePaste assigns a File, other paths assign strings, and the template feeds it to an <input value> that accepts neither. No annotation describes the current code — the render path has to be fixed first. Left untyped with a TODO(#35943) so it is not re-annotated in isolation.

---

sdk-react (#35945)

strict: true was already present; the five companion flags were not. Adding them surfaced 14 errors, all TS4111 — dot access on a type carrying an index signature — resolved with bracket notation. Two origins, same fix:

• 13 from node.attrs, declared Record<string, any> in @dotcms/types. That type is deliberately left alone: block editor attributes really are dynamic, and it lives in a layer-0 project whose consumers would all be affected.
• 1 from CSS Modules (styles.row in Row.tsx), whose generated type is also a Record<string, string>.

No behaviour change — bracket access compiles to the same property lookup.

The flags here are genuinely enforced, and that was proved rather than assumed. Reverting one access to dot notation fails the build with @rollup/plugin-typescript TS4111, confirming TypeScript sits in the Rollup chain. The project carries no skip: tags, so CI builds, lints and tests it on every PR, and the same build runs in the SDK release pipeline.

One error remains under plain tsc and is expected: Cannot find module 'virtual:sdk-version' in sdk-client — a Vite virtual module that raw tsc cannot resolve but the build can. It predates this change and is unrelated to strict mode. Worth knowing when measuring, or the count reads 15 instead of 14.

Test plan

dotcms-js

• pnpm exec tsc -p libs/dotcms-js/tsconfig.lib.json --noEmit — 0 errors (from 38)
• All six already-strict consumers build green: data-access, global-store, portlets-dot-analytics, portlets-dot-analytics-data-access, portlets-dot-locales-portlet, utils-testing
• data-access typecheck: 106 → 68 errors, zero new
• dotcms-ui typecheck clean (one pre-existing unrelated error)
• dotcms-js lint went from 42 to 41 problems (still tag-excluded)

sdk-create-app

• tsc --noEmit clean on lib and spec
• nx run sdk-create-app:build / :lint / :test green
• CLI smoke test: node dist/libs/sdk/create-app/index.js --help works
• Negative test: reverting the DEBUG fix makes nx run sdk-create-app:build fail with TS4111 — confirming the build gate is real

Both

• pnpm exec nx format:check --base=origin/main green
• No new any / @ts-ignore / @ts-expect-error (verified by diff grep)

Note: neither sdk-create-app nor dotcms-js has usable tests. sdk-create-app has zero test files (passWithNoTests: true); dotcms-js has 3 spec files that do not run (skip:test, and tsconfig.spec.json fails on a pre-existing jasmine types error). A green :test means nothing for either — the real verification is compilation.

---

Correction: a verification false negative (review follow-up)

A review comment caught a real regression this PR introduced, and the reason it slipped through matters for how the numbers above should be read.

libs/utils-testing/tsconfig.lib.json declares "types": ["jasmine"], and that package is not installed. tsc therefore emits TS2688: Cannot find type definition file for 'jasmine' and stops before semantic checking. So tsc -p libs/utils-testing/tsconfig.lib.json --noEmit reports exactly one error no matter what the code does.

The utils section originally reported "utils-testing unchanged at 1 pre-existing error" as evidence of no regression. That measurement proved nothing — nothing was being type-checked. Running the same config with --types node reveals 33 errors, including a genuine TS2741 caused by retyping EMPTY_SYSTEM_FIELD to Omit<DotCMSContentTypeField, 'clazz'>: the mock at dot-content-types.mock.ts:71 spreads it and never supplies clazz.

Fixed by giving the mock clazz: DotCMSClazzes.TEXT; that config is now at 32 errors, all pre-existing and unrelated.

Because the mock has ~103 consumers whose tests do run in CI, the runtime-value change was verified rather than assumed — clazz went null (pre-PR) → absent (this PR) → TEXT:

• FieldUtil.isRow / isColumn / isTabDivider compare for equality and return false for all three values.
• There is no !field.clazz or field.clazz === null anywhere in the repo.
• Test runs: default-value-property 7/7; dot-content-types-edit 545 passed across 48 suites; data-access 751 passed across 79 suites.

The data-access figures reported elsewhere in this PR (106 → 68 for dotcms-js, 68 → 36 for utils) are not affected — that project has no unresolved types entry, so those runs were doing real semantic checking.

core-web/CLAUDE.md now documents this masking behaviour so the next person does not repeat it.

Other two comments

• sdk-create-app — the throw said "requires at least 1 retry", but retries is the total attempt count (for (i = 0; i < retries; i++)), so retries = 1 is one attempt and zero retries. Reworded to "attempt".
• CLAUDE.md verify snippet — hard-coded libs/<project>/tsconfig.lib.json, which resolves for neither nested projects (libs/sdk/create-app, which has no tsconfig.lib.json) nor apps (tsconfig.app.json). Replaced with a <projectRoot> placeholder and both caveats.

Notes for reviewers

Three sibling issues in this rollout turned out not to need the work as written, and were resolved separately:

• [03/44] Enable TS strict mode in dotcms #35936 (dotcms) and [04/44] Enable TS strict mode in dot-layout-grid #35937 (dot-layout-grid) — closed as not applicable. Both are dead libraries with zero consumers that do not compile today; removal is tracked in Remove dead core-web libraries (libs/dotcms, libs/dot-layout-grid) #36950.
• The epic description was updated (44 → 42 projects) and corrected: it documented a typescript-strict-plugin / tsc-strict approach that was dropped — the bootstrap [00] Setup typescript-strict-plugin baseline + CI gate #35933 closed without the plugin ever landing. Sub-issues still referencing npx tsc-strict or // @ts-strict-ignore carry stale acceptance criteria; [06/44] Enable TS strict mode in dotcms-js #35939's were corrected on the issue.

Closes #35945
Closes #35944
Closes #35940
Closes #35939
Closes #35938
Closes #35935

[claude]

Claude finished @nicobytes's task in 1m 39s —— View job

---

Code Review

Reviewed the diff against origin/main. This is a TS-strict-mode rollout: almost all changes are type-level (widening return types to reflect reality, !/? decorator annotations in webcomponents, bracket access for index signatures). I focused on the handful of sites where runtime behavior could shift.

New Issues

No blocking issues found. The substantive logic changes are behavior-preserving:

• response-view.ts — removing the dead try/catch and adding ?. guards is safe; HttpResponse.body was already nullable and the old catch could never fire. The new errorsMessages returns '' instead of throwing when the body is null — a strict improvement.
• dot-utils.ts:ellipsizeText — limit == null added before limit <= 0 || isNaN(limit); undefined/null produce the same '' result the old code did via isNaN.
• FieldUtil.ts:EMPTY_FIELD — null → zero-values and Omit<…, 'clazz'> is consistent with the falsy-check consumers; the dot-content-types.mock.ts fix (clazz: DotCMSClazzes.TEXT) correctly repairs the spread that the Omit would otherwise leave incomplete.
• login.service.ts / site.service.ts — the two ! definite-assignment assertions are documented with TODO(#35939) and keep the public getter types unchanged, avoiding an API break for strict consumers.

Resolved

• ✅ core-web/libs/sdk/create-app/src/utils/index.ts:125 — Copilot's note on the misleading "retry" wording is fixed; the throw now reads "requires at least 1 attempt" and adds a clarifying comment that retries is the total attempt count.
• ✅ core-web/CLAUDE.md — Copilot's note on the hard-coded libs/<project>/tsconfig.lib.json path is fixed; it now uses a <projectRoot> placeholder with explicit caveats for apps (tsconfig.app.json) and projects without a tsconfig.lib.json.

Notes (non-blocking)

• site.service.mock.ts — _currentSite is now Site | undefined while get currentSite(): Site still declares a non-nullable return. This is only internally consistent because dotcms-js has no build/typecheck gate (as the PR itself flags). Not a runtime bug, but the getter type is now technically lying — worth a follow-up when the enforcement gap is closed.

The self-documented enforcement gap for dotcms-js and utils (no build target, tag-excluded from lint/test → nothing in CI verifies these flags) is an accepted, clearly-disclosed trade-off, not a defect in this PR.

Overall: clean. Approve from a correctness standpoint.
· 35932-enable-strict-mode

[Copilot]

Pull request overview

This PR opts the sdk-create-app library into the workspace’s incremental TypeScript strict-mode rollout (issue #35932), and adjusts docs/runtime code to align with stricter typing and clearer failure modes.

Changes:

• Enabled strict TypeScript compiler flags for core-web/libs/sdk/create-app via its project tsconfig.json.
• Updated fetchWithRetry to throw when misconfigured with < 1 attempts to avoid an implicit undefined return path.
• Updated strict-mode rollout documentation and adjusted DEBUG env access to bracket notation for noPropertyAccessFromIndexSignature.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
core-web/libs/sdk/create-app/tsconfig.json	Enables strict compiler options at the project level for the strict-mode rollout.
core-web/libs/sdk/create-app/src/utils/index.ts	Adds an explicit throw path for invalid retries values in fetchWithRetry.
core-web/libs/sdk/create-app/src/index.ts	Switches DEBUG env access to process.env['DEBUG'] for strict-mode compatibility.
core-web/CLAUDE.md	Documents the strict-mode rollout procedure and clarifies portlet tsconfig guidance.