i18next / i18next/react-i18next
Make the global HTMLAttributes children type augmentation opt-in (next major)
- Dominant language
- JavaScript
- Stars
- 10k
- Forks
- 1k
- Avg merge
- 6m
- Merged PRs (30d)
- 1
Description
## Context
`index.d.ts:174-187` ships a `declare module 'react'` global augmentation that overrides `HTMLAttributes.children` (plus `JSX.IntrinsicAttributes.i18nIsDynamicList`) for **every** consumer of react-i18next, whether or not they use the feature it exists for.
The children override is defanged by default (`ReactI18NextChildren` resolves the object case to `never` unless `CustomTypeOptions.allowObjectInHTMLChildren` is `true`), but it still patches React's global types and remains the one coupling point to React's internal type shape. It has clashed before (#1681, "HTMLAttributes is not assignable to DOMAttributes", Sep 2023) and every React major forces a re-check of this block (see the React 18 wave: #1476, #1483, #1543).
## Proposal (next major)
Move the augmentation into an opt-in ambient module, e.g.:
```ts
// only needed when CustomTypeOptions.allowObjectInHTMLChildren is true
import 'react-i18next/augment-react';
```
Default installs then never touch React's global types.
## Breaking-change note
Users who currently set `allowObjectInHTMLChildren: true` must add the one-line import; needs a prominent migration-guide entry.
## Related mitigation already in place
The weekly types-compat workflow (`.github/workflows/types-compat.yml`, since 17.0.10) typechecks against the newest `@types/react` (pre-release tags when available), so breakage from upstream type changes is caught early either way.
Contributor guide
Research direction
Start with index.d.ts:174-187 and trace the existing React augmentation and CustomTypeOptions.allowObjectInHTMLChildren handling. Review .github/workflows/types-compat.yml for the relevant type checks, then define the opt-in augment-react entry point and update the migration guide so the new import requirement is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- frontend, internationalization
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100