i18next / i18next/react-i18next

Make the global HTMLAttributes children type augmentation opt-in (next major)

Open
#1,928 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.