Problem
LiveStore's Effect v4 migration surfaced that effect-utils still exports an Effect v3 dependency catalog. Downstream megarepos that compose effectUtilsCatalog inherit obsolete v3 package names and versions unless they explicitly filter them out.
In LiveStore PR livestorejs/livestore#1322, we had to add a local filter for obsolete v3-era Effect packages before composing the LiveStore catalog. That is a pragmatic local workaround, but it leaves the shared catalog source in effect-utils on the old dependency model.
Current downstream impact
The inherited catalog still includes v3-era packages that Effect v4 consolidates into effect or unstable module paths, such as:
@effect/ai@effect/cli@effect/cluster@effect/experimental@effect/platform@effect/printer@effect/printer-ansi@effect/rpc@effect/sql@effect/typeclass@effect/workflow
That means downstream generated manifests can accidentally reintroduce obsolete v3 package peers or overrides via catalog.pick(...).
Desired outcome
Migrate effect-utils dependency generation to Effect v4 so downstream repos can compose the shared catalog without local deny-lists.
A good solution should:
- establish the Effect v4 package/version source of truth in
effect-utils
- remove or replace obsolete v3-era Effect package entries from generated catalogs and peer-dependency helpers
- keep remaining separate Effect packages explicit, e.g. provider/platform/tooling packages that still exist in v4
- update generated package metadata and lockfile through the normal Genie/pnpm workflow
- decide whether the catalog API should expose a safer
omit/category split for cross-major migrations
Suggested implementation notes
LiveStore's temporary workaround filters the inherited catalog before composing its own catalog:
const effectUtilsCatalogWithoutEffectV3 = Object.fromEntries(
Object.entries(effectUtilsCatalog).filter(
([name]) => obsoleteEffectV3PackageNames.has(name) === false && effectV4CatalogPackageNames.has(name) === false,
),
)That pattern could be replaced by one of:
- migrating the base
effect-utils catalog directly to v4
- splitting exports into Effect-specific and non-Effect catalog subsets
- adding a first-class catalog omit helper if downstream repos still need selective composition
Acceptance criteria
effect-utils generated dependency metadata resolves Effect v4 consistently.- Obsolete v3-era Effect packages are no longer exposed as normal catalog entries unless intentionally preserved for compatibility with a documented reason.
- Generated package manifests and lockfile are up to date.
- Downstream megarepos no longer need local filters solely to prevent v3 Effect catalog leakage.
- Validation commands and any remaining migration blockers are documented.
Related context
Problem
LiveStore's Effect v4 migration surfaced that
effect-utilsstill exports an Effect v3 dependency catalog. Downstream megarepos that composeeffectUtilsCataloginherit obsolete v3 package names and versions unless they explicitly filter them out.In LiveStore PR livestorejs/livestore#1322, we had to add a local filter for obsolete v3-era Effect packages before composing the LiveStore catalog. That is a pragmatic local workaround, but it leaves the shared catalog source in
effect-utilson the old dependency model.Current downstream impact
The inherited catalog still includes v3-era packages that Effect v4 consolidates into
effector unstable module paths, such as:@effect/ai@effect/cli@effect/cluster@effect/experimental@effect/platform@effect/printer@effect/printer-ansi@effect/rpc@effect/sql@effect/typeclass@effect/workflowThat means downstream generated manifests can accidentally reintroduce obsolete v3 package peers or overrides via
catalog.pick(...).Desired outcome
Migrate
effect-utilsdependency generation to Effect v4 so downstream repos can compose the shared catalog without local deny-lists.A good solution should:
effect-utilsomit/category split for cross-major migrationsSuggested implementation notes
LiveStore's temporary workaround filters the inherited catalog before composing its own catalog:
That pattern could be replaced by one of:
effect-utilscatalog directly to v4Acceptance criteria
effect-utilsgenerated dependency metadata resolves Effect v4 consistently.Related context