"Type 'undefined' is not assignable" errors after enabling exactOptionalPropertyTypes on a shared library

Answer the question first

• Rewrite every optional property as prop?: T | undefined if you need the library to be usable by consumers that keep exactOptionalPropertyTypes disabled.
• Alternatively, enforce a single tsconfig setting (either enable or disable the flag) across all packages in the monorepo. That removes the divergent semantics entirely.
• Enabling the flag only in the library but not in consumers does create unsound typing at the package boundary: a consumer can pass { prop: undefined } and the library will treat the property as absent, potentially breaking runtime assumptions.
• The flag remains outside strict so that existing codebases can migrate gradually. It is an opt‑in feature introduced in TS 4.8 to give teams control over the stricter optional‑property semantics.

Why exactOptionalPropertyTypes matters

When exactOptionalPropertyTypes is true, the compiler treats prop?: T as "property may be omitted, but if present it must be of type T". Explicit undefined is rejected. With the flag off, prop?: T is equivalent to prop?: T | undefined, allowing consumers to write { prop: undefined }.

Unsoundness across package boundaries

Suppose the library declares

interface Foo { prop?: string; }

and is compiled with exactOptionalPropertyTypes enabled. A consumer compiled with the flag disabled can write:

const foo: Foo = { prop: undefined };

The library will treat prop as absent, but the runtime code may still expect a defined string. This mismatch is a classic example of unsoundness introduced by different compiler flags.

Practical steps to keep APIs consistent

1. Audit public interfaces. Search for all optional properties in the library’s *.d.ts files.
2. Choose a policy.
   • If the library’s intent is that optional props are truly optional (absent or defined), enable exactOptionalPropertyTypes in every package and update consumers accordingly.
   • If some consumers must still accept undefined, rewrite those properties as prop?: T | undefined.
3. Re‑compile and test. Build the library, generate its declaration files, and import them into a consumer project with the opposite flag setting. Verify that the compiler error disappears when the property is rewritten, and that the code compiles when the flag is unified.
4. Document the decision. Add a comment in the library’s README or a dedicated tsconfig.json note explaining the chosen flag policy to avoid future drift.

What if you need both behaviors?

In rare cases you may want to expose a type that accepts undefined while still keeping the stricter semantics for internal use. You can create a separate interface for the consumer API:

interface FooConsumer = Omit & { prop?: string | undefined };

Export FooConsumer for external consumers, and keep Foo for internal code.

Summary

Standardize exactOptionalPropertyTypes across the monorepo or explicitly widen optional types to ... | undefined if you must keep divergent settings. The flag is opt‑in to allow gradual migration; keeping it disabled in some packages while enabled in others introduces unsoundness at the boundary.