Proposal: optional module override resolver (file-level overrides without patching core)

[likeabas]

Related: #12641 (this complements the hook/plugin idea there and follows up on my comment in that thread)

Problem

Forks that need to swap a module (a hook, a route, a component) currently have to patch core imports, e.g. import … from '~/extensions/…'. Every swap touches upstream files, which causes merge conflicts on every sync. Hooks (#12641) cover additive behavior well, but they don't help when a whole module needs to be replaced or wrapped.

Proposal

A small, opt-in resolver that works by convention:

Core keeps importing its normal paths. At resolve time, if overrides/<same relative path> exists in that package's source root, use it. Otherwise use the stock file.

With no overrides/ directory, behavior is identical to vanilla LibreChat.

client/src/hooks/Files/useFileHandling.ts            # stock
client/src/overrides/hooks/Files/useFileHandling.ts  # optional override

api/server/routes/files/files.js                     # stock
api/overrides/server/routes/files/files.js           # optional override

Resolve rules

1. Only alias/absolute imports into the package source root (e.g. ~/…) are considered.
2. Relative imports (./, ../) are never rewritten. This lets an override wrap the stock module via a relative import, without loops.
3. Imports originating from within overrides/ are not redirected again.
4. Same extension candidates as the normal resolver (.ts, .tsx, .js, /index).

Implementation: one shared resolve function (stockPath → overridePath | null) with thin adapters:

Tool	Hook
Vite (client)	resolveId plugin (dev, build, HMR)
Node (api/)	module.register / _resolveFilename, alongside the existing ~ alias
Jest	custom resolver
tsdown/esbuild (packages/*)	resolve plugin

Error handling: a broken override fails fast rather than silently falling back to stock. An optional OVERRIDE_RESOLVE_DEBUG=1 logs which modules were overridden.

Known limitation: TypeScript paths can't express "if file exists", so "go to definition" on a stock import opens the stock file.

Questions for maintainers

1. Are you open to this as an optional, convention-based mechanism in core?
2. Would you rather see this land alongside a hook API (Support Extensions/plugins to expand functionality #12641), or not at all in favor of hooks only?
3. Any preference on the directory name (overrides/) or opt-in mechanism (env flag vs. always on)?

We have a PoC in progress and are happy to implement and maintain it.