Распространённые ошибки TypeScript в React и способы их устранения

Если вы пришли из JavaScript, TypeScript может показаться сначала пугающим. В первые дни кажется, что компилятор активно работает против вас: повсюду красные и желтые изогнутые линии, загадочные сообщения, которые, кажется, никуда не ведут... и в какой-то момент вы можете начать сомневаться, было ли действительно правильным переход на TypeScript, задумываясь, не проще ли вернуться к обычному JavaScript.

Но дело в том, что внедрение TypeScript в кодовую базу React — один из самых умных шагов, которые вы можете сделать, если хотите поддерживать качество кода со временем.

А те ошибки и предупреждения, с которыми вы постоянно сталкиваетесь? Им определенно стоит противостоять, вам просто нужно научиться распознавать повторяющиеся закономерности за ними.

Большинство проблем с TypeScript, с которыми вы сталкиваетесь при разработке React-приложений, совсем не являются случайными. Одни и те же ошибки постоянно встречаются в разных проектах, и после нескольких случаев их решения вы сможете мгновенно их распознавать и точно понимать, что они означают. В этой статье рассматриваются пять категорий ошибок, которые встречаются практически в каждом React-проекте на TypeScript, объясняется причина возникновения каждой из них и способ её устранения.

Один совет перед началом: всегда читайте полное сообщение об ошибке. Ошибки TypeScript на первый взгляд могут показаться страшными, но на самом деле они имеют довольно предсказуемую структуру. Не позволяйте обилию текста сбить вас с толку, и если вы не знаете, с чего начать, последняя строка сообщения обычно является самой полезной для анализа.

С этими словами перейдём к делу.

1. Ошибки свойств компонентов

Параметры являются основой каждого компонента React, поэтому неудивительно, что ошибки типов, связанные с параметрами, обычно встречаются у разработчиков первыми.

Ошибка: Свойство 'X' отсутствует в типе '{}'.

Эта ошибка появляется, когда вы используете параметр в своем компоненте, не задав для него определение типа.

// This won't give any errors in JavaScript...
function UserCard({ name, email }) {
  return (
    <div>
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

// But in TypeScript...
// Error: Parameter 'name' implicitly has an 'any' type
// Error: Parameter 'email' implicitly has an 'any' type

Эта ошибка возникает просто потому, что параметрам никогда не задавались явные типы.

Решение: объявите интерфейс, описывающий ваши параметры.

interface UserCardProps {
  name: string;
  email: string;
};

function UserCard({ name, email}: UserCardProps) {
  return (
    <div>
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

Ошибка: Тип 'string' нельзя присвоить типу 'number'.

Эта ошибка довольно проста в понимании: это означает, что вы передали параметр с значением неправильного типа.

Решение: проверьте тип значения, которое вы передаете в параметр.

interface ItemForSaleProps {
  imgUrl: string;
  itemName: string;
  amount: number;
  currency: string;
};

function ItemForSale({
  itemName,
  imgUrl,
  amount,
  currency
}: ItemForSaleProps) {
  return (
    <div class="item-for-sale">
      <img src={imgUrl} alt="item image" />
      <h5>{itemName}</h5>
      <p>{`${currency} ${amount.toFixed(2)}`}</p>
    </div>
  );
};

// Error happens when passing a string where a number is expected.
<ItemForSale
  imgUrl="api.example.com/image"
  itemName="Sample"
  amount="10.99"
  currency="USD"
/>

// Should be like this
<ItemForSale
  imgUrl="api.example.com/image"
  itemName="Sample"
  amount={10.99}
  currency="USD"
/>

Заметили разницу между двумя версиями? Компонент ItemForSale ожидает, что параметр amount будет иметь тип number, поэтому передача строкового значения вызывает ошибку, тогда как передача настоящего числового значения является правильной. Это и есть то, для чего предназначен TypeScript — он выявляет потенциальные ошибки ещё до запуска кода. В этом примере вызов метода .toFixed(2) для строки '10.99' фактически привёл бы к сбою во время выполнения, но TypeScript обнаруживает проблему уже на этапе компиляции.

Ошибка: В типе '{}' отсутствует свойство 'X', которое требуется в типе 'Props'.

Это происходит, когда свойство указано как обязательное в интерфейсе, но вы забываете его передать при использовании компонента.

interface CustomButtonProps {
  label: string;
  onClick: () => void;
};

function CustomButton({ label, onClick }: CustomButtonProps) {
  return <button onClick={onClick}>{label}</button>;
};

// Bad usage:
<CustomButton label="Submit" />
// Error: Property 'onClick' is missing in type '{ label: string; }'
// but required in type 'ButtonProps'

Решение: тщательно проверьте как определения свойств в вашем компоненте, так и те свойства, которые вы фактически передаёте при его отрисовке.

// Correct usage:
<CustomButton label="Submit" onClick={handleSubmit} />

Иногда бывают свойства, которые не всегда нужны. В таких случаях вы можете отметить свойство как необязательное с помощью ?. Помните, что когда вы делаете свойство необязательным, вам также следует указать значение по умолчанию или какой-то способ проверки на null, чтобы безопасно обрабатывать его отсутствие.

interface CustomButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;   // this prop is now optional
  className?: string;   // this one too
};

function CustomButton({ label, onClick, disabled = false, className }: CustomButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={className}
    >
      {label}
    </button>
  );
};

// This component now works with or without the optional props
<CustomButton label="Submit" onClick={handleSubmit} />
<CustomButton label="Submit" onClick={handleSubmit} disabled={true} />

Теперь, когда речь идёт о необязательных свойствах, стоит упомянуть ещё одну ошибку.

Ошибка: тип 'X | undefined' нельзя присвоить типу 'X'.

Сделав свойство необязательным, вы автоматически добавляете undefined к его типу, что приводит к проблемам, если вы пытаетесь использовать это значение без предварительной проверки на его наличие.

interface ProfileProps {
  name: string;
  bio?: string;
};

function Profile({ name, bio }: ProfileProps) {
  return (
    <p>{name}</p>
    <p>{bio.toUpperCase()}</p>
    // Error: Object is possibly 'undefined'
  );
};

Как правило, существует три способа решения этой проблемы:

Вариант 1: указать значение по умолчанию при деконструкции пропсов.

// bio is always a string, will render a default text when there's
// no bio provided
function Profile({ name, bio = 'No bio available' }: ProfileProps) {
  return (
    <p>{name}</p>
    <p>{bio.toUpperCase()}</p>
  );
};

Вариант 2: воспользоваться опциональным цепочковым доступом.

// returns undefined if bio is undefined
function Profile({ name, bio }: ProfileProps) {
  return (
    <p>{name}</p>
    <p>{bio?.toUpperCase()}</p>
  );
};

Вариант 3: использовать условную отрисовку.

// will only render if bio exists
function Profile({ name, bio }: ProfileProps) {
  return (
    <p>{name}</p>
    <p>{bio && bio.toUpperCase()}</p>
  );
};

2. Ошибки обработчиков событий

Любой компонент React, реагирующий на действия пользователя, нуждается в обработчиках событий, причем TypeScript предоставляет очень точные типы для каждого вида событий DOM. Неправильное указание этих типов является одной из наиболее частых причин путаницы у разработчиков, работающих с типизированным кодом React.

Проблема: параметр 'e' имплицитно имеет тип 'any'.

Это происходит, когда вы пишете обработчик событий в виде отдельной функции вне JSX и забываете указать тип параметра события.

// Error: Parameter 'e' implicitly has an 'any' type
const handleClick = (e) => {
  e.preventDefault();
};

Решение: Привязать соответствующий тип события React к параметру.

const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  e.preventDefault();
};

Стоит отметить: когда вы пишете обработчик непосредственно внутри JSX, TypeScript может сам определить тип, поэтому в таком случае эта ошибка не появится.

<button onClick={(e) => {
  e.preventDefault() // e is automatically React.MouseEvent<HTMLButtonElement>
}}>
  Click here
</button>

Проблема: Свойство 'value' отсутствует у типа 'EventTarget'.

Это, вероятно, самая популярная ошибка TypeScript среди разработчиков React — её также трудно понять при первом столкновении. Она появляется, когда вы пытаетесь прочитать e.target.value внутри обработчика изменений.

// This will give an error because TS doesn't know target is an input element.
const handleChange = (e: React.ChangeEvent) => {
  console.log(e.target.value);
  // Error: Property 'value' does not exist on type 'EventTarget'
};

Коренная причина заключается в том, что EventTarget — это универсальный интерфейс DOM, поэтому TypeScript не может знать, что в этом конкретном обработчике целевым элементом является именно <input>, у которого произвольно имеется свойство value.

Решение: Укажите конкретный тип элемента в качестве генерического параметра для типа события.

// TypeScript now knows the target is an HTMLInputElement
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  console.log(e.target.value);
};

Тот же принцип применим и к другим элементам — для элемента select, например, замените HTMLInputElement на HTMLSelectElement. Вот краткий справочник по наиболее часто используемым типам событий:

// Click events
onClick: (e: React.MouseEvent<HTMLButtonElement>) => void
onClick: (e: React.MouseEvent<HTMLDivElement>) => void

// Input change events
onChange: (e: React.ChangeEvent<HTMLInputElement>) => void
onChange: (e: React.ChangeEvent<HTMLSelectElement>) => void
onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void

// Form submission
onSubmit: (e: React.FormEvent<HTMLFormElement>) => void

// Keyboard events
onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void
onKeyUp: (e: React.KeyboardEvent<HTMLInputElement>) => void

// Focus events
onFocus: (e: React.FocusEvent<HTMLInputElement>) => void
onBlur: (e: React.FocusEvent<HTMLInputElement>) => void

Поскольку мы говорим о обработчиках событий, возможно, вас интересует, как правильно задавать их тип при передаче в качестве свойств дочерним компонентам. В таком случае их следует описывать как функции, принимающие соответствующий объект события.

interface SearchInputProps {
  onSearch: (e: React.ChangeEvent<HTMLInputElement>) => void;
  onSubmit: (e: React.FormEvent<HTMLFormElement>) => void;
};

function SearchInput({ onSearch, onSubmit }: SearchInputProps) {
  return (
    <form onSubmit={onSubmit}>
      <input type="text" onChange={onSearch} />
      <button type="submit">Search</button>
    </form>
  );
};

А если тот или иной обработчик вообще не нуждается в событии, его тип можно упростить соответственно.

interface SearchInputProps {
  onClick: () => void;
  onHover: () => void;
};

3. useState и useRef

Hooks занимают центральное место в современном разработке на React, поэтому неудивительно, что useState и useRef имеют свои особенности в TypeScript.

Проблема: Аргумент типа 'X' нельзя присвоить параметру типа 'never'.

Это одна из самых непонятных ошибок, с которыми можно столкнуться. Она возникает, когда вы инициализируете useState пустым массивом, из-за чего TypeScript интерпретирует тип состояния как never[]. Вот пример:

// TypeScript infers state type as never[]
const [items, setItems] = useState([]);

// So later when we try to set a value...
setItems([{ id: 1, name: 'Item 1' }]);
// Error: Argument of type '{ id: number; name: string; }[]' is not assignable
// to parameter of type 'never[]'

Причина этого заключается в том, что когда начальное значение состояния — пустой массив, у TypeScript нет способа определить, какие элементы в конечном итоге окажутся внутри него, поэтому он использует тип never[] по умолчанию.

Решение: Всегда указывайте явный аргумент типа, когда начальное состояние — пустой массив или null.

interface Item {
  id: number;
  name: string;
}

// ✅ Explicitly typed
const [items, setItems] = useState<Item[]>([]);
const [selectedItem, setSelectedItem] = useState<Item | null>(null);

В этом фрагменте тип состояния selectedItem явно задан так, чтобы принимать либо объект Item, либо null. Каждый раз, когда вы ожидаете, что какое-либо состояние изначально будет пустым и заполнится позже, необходимо четко указать это для TypeScript — в противном случае возникнет следующая ошибка:

Тип 'null' не может быть присвоен типу 'X'.

interface User {
  id: number;
  name: string;
  email: string;
}

// TypeScript infers state as User, not User | null
const [user, setUser] = useState<User>({} as User); // Dangerous cast

// Later...
if (user.name) { /* ... */ }
// This might not catch the case where user is empty

Решение: Используйте объединительный тип, включающий null, чтобы TypeScript понимал, что данные еще не загружены.

// Correctly typed, can be type User or null
const [user, setUser] = useState<User | null>(null);

// Now TypeScript forces you to handle the null case
if (user) {
  console.log(user.name); // TypeScript knows user is User here
}

// Or with optional chaining:
console.log(user?.name); // string | undefined

Та же идея применима, когда состояние хранит более сложный объект. Допустим, вы моделируете состояние формы контактов с несколькими полями — правильный подход заключается в том, сначала определить интерфейс, описывающий его структуру.

interface FormState {
  name: string;
  email: string;
  message: string;
  isSubmitting: boolean;
}

function SubmitMessageForm() {
  const [form, setForm] = useState<FormState>({
    name: '',
    email: '',
    message: '',
    isSubmitting: false,
  });

  // Then do partial updates with spread operator
  const handleChange = (field: keyof FormState, value: string) => {
    setForm(prevState => ({ ...prevState, [field]: value }));
  };
}

Проблема: Объект может быть равен 'null'.

Эта ошибка постоянно возникает, когда референс, созданный с помощью useRef, изначально имеет значение null, но должен указывать на элемент DOM. TypeScript выдает предупреждение при любой попытке использования этого референса до тех пор, пока не будет подтверждено, что в нем действительно есть значение.

const inputRef = useRef<HTMLInputElement>(null);

// Typescript here knows that inputRef.current might be null
inputRef.current.focus();

// Error: Object is possibly 'null'

Решение: проверяйте, что переменная current задана, прежде чем использовать её. Как только TypeScript обнаруживает такую проверку, оно прекращает выдавать предупреждения, поскольку больше не может доказать, что значение может быть null.

// Null check before use
const handleFocus = () => {
  if (inputRef.current) {
    inputRef.current.focus();
  }
};

// Or if you're more into one-liners, you can use optional chaining
inputRef.current?.focus();

Прежде чем перейти к следующей категории, стоит отметить важное изменение. React 19 изменил поведение функции useRef таким образом, что это создаёт трудности у многих разработчиков — а именно в отношении различия между RefObject<T|null> и MutableRefObject<T>. Теперь поведение определяется не начальным значением, которое вы передаёте, а параметром генерического типа, указанным для этой функции.

До React 19 вызов useRef(null) всегда возвращал объект типа MutableRefObject<T>, поэтому поле current всегда можно было перезаписать.

// This worked fine
const ref = useRef<HTMLInputElement | null>(null);
ref.current = someElement;

Начиная с React 19, именно указанный вами генерический тип определяет, можно ли изменять значение поля current.

const ref = useRef<HTMLInputElement>(null);
ref.current = someElement;
// The above will result in an error.

Здесь, поскольку генерический параметр представляет собой тип HTML-элемента, React 19 рассматривает ref как тот, который указывает на DOM, поэтому он становится только для чтения и фактически управляется самим React.

Если вам нужен ref для хранения изменяемого значения вместо узла DOM, делайте следующее:

// Let's suppose we're building a timer
const ref = useRef<ReturnType<typeof setTimeout> | null>(null);
ref.current = setTimeout(() => {}, 1000);

Это работает потому, что тип, переданный в генерик, не является типом HTML-элемента, поэтому React рассматривает его как обычный изменяемый ref — current остается доступным для присваивания.

Правило для React 19: когда генерический тип — это тип HTML-элемента, current становится только для чтения и контролируется React. Когда же это любой другой тип, current остается доступным для записи. Короче говоря:

• useRef<HTMLElement>(null) для узлов DOM, управляемых React (только для чтения)

useRef<T|null>(null) — для любого другого изменяемого значения, которое вы хотите сохранить сами

4. Асинхронные данные и ошибки API

Как только вы начинаете получать данные из API, появляется новый набор ошибок TypeScript, потому что полученные данные изначально имеют тип unknown и должны пройти несколько преобразований, прежде чем стать тем, что можно безопасно использовать.

Ошибка: Тип 'unknown' нельзя присвоить типу 'X'.

По умолчанию результат вызова fetch имеет тип unknown, поскольку TypeScript не знает заранее, какой формы будут возвращаться данные с определенного конца API.

// Fetch response is unknown
const response = await fetch('/api/users');
const data = await response.json(); // data: any (in older TS) or unknown

// So when trying to use the fetched data:
const userName = data.name;

// With the code above, you might get a warning, something like
// 'data' is of type 'unknown'

Решение: явно указать тип ответа от API.

interface User {
  id: number;
  name: string;
  email: string;
};

После этого у вас обычно есть два варианта применения этого типа:

// Option 1: Type assertion. Only use this when you trust the API shape.
const response = await fetch('/api/users/1');
const data = await response.json() as User;
console.log(data.name); // You'll see that you have a string here

//////////////////////////////////////////////////////////////////////////

// Option 2: Create a generic fetch wrapper, this is a safer approach
// and it's reusable.
async function fetchJSON<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  return response.json() as Promise<T>;
}
const user = await fetchJSON<User>('/api/users/1');
console.log(user.name); // TypeScript now knows this is a string

5. Дочерние элементы и ошибки JSX

Компоненты в React обычно принимают и отображают children, и TypeScript предлагает несколько перекрывающихся типов для описания того, чем могут быть эти дети. Знание их различий помогает избежать целого ряда ошибок типов.

Три типа часто используются так, как будто они взаимозаменяемы, хотя это не так:

• ReactNode
• ReactElement
• JSX.Element

Из них ReactNode и ReactElement действительно различаются, в то время как JSX.Element на самом деле является просто другим названием для ReactElement.

import { ReactNode, ReactElement } from 'react';

// ReactNode is the most permissive one, accepts basically
// everything React can render:
// string, number, boolean, null, undefined, ReactElement, arrays...

type ReactNode =
  | ReactElement
  | string
  | number
  | boolean
  | null
  | undefined
  | ReactPortal
  | Iterable<ReactNode>;

// ReactElement is literally a React element created by
// JSX or React.createElement
// It does not include string, number, null, undefined
type ReactElement = {
  type: string | ComponentType;
  props: any;
  key: string | null;
};

Как правило: используйте ReactNode для свойства children, если у вас нет конкретной причины для его узкой спецификации.

// Most flexible: use ReactNode for children in most cases
interface CardProps {
  children: ReactNode;
};

// And use ReactElement when the requirements are not very flexible
interface StrictWrapperProps {
  children: ReactElement;
};

Стоит более точно разъяснить разницу между ReactNode и ReactElement.

ReactNode может представлять собой что угодно из следующего:

const example1 = <div>Hello</div>;        // ReactElement ✅
const example2 = "Hello";                 // string ✅
const example3 = 42;                      // number ✅
const example4 = true;                    // boolean ✅ (renders nothing)
const example5 = null;                    // null ✅ (renders nothing)
const example6 = undefined;               // undefined ✅ (renders nothing)
const example7 = [<div />, <span />];     // array of ReactElements ✅

// All of the above are ReactNode

С другой стороны, ReactElement имеет более строгие ограничения:

const example1 = <div>Hello</div>;
const example2 = <Button onClick={someHandlerFn}>Submit</Button>;
const example3 = React.createElement('div', null, 'Hello');

// Under the hood, every ReactElements look like this:
{
  type: 'div',
  props: { children: 'Hello' },
  key: null,
}

Ошибка: Тип 'X' не может быть присвоен типу 'ReactNode'.

Эта ошибка обычно возникает, когда вы пытаетесь отрендерить значение, которое TypeScript не считает допустимым для отображения.

// Objects are not a valid React children
interface User {
  name: string;
  email: string;
}


// Then if you try to do this
function DisplayUser({ user }: { user: User }) {
  return <div>{user}</div>;
}

// It'll probably give you an error that looks something like...
// Error: Type 'User' is not assignable to type 'ReactNode'
// Objects are not valid React Children

Решение: отрендерьте отдельные поля вместо всего объекта.

function DisplayUser({ user }: { user: User }) {
  return (
    <div>
      <p>{user.name}</p>
      <p>{user.email}</p>
    </div>
  );
}

Ошибка: У типа элемента JSX 'X' нет подписей конструктора или вызова.

Сначала это может вызвать путаницу. Эта ошибка появляется, когда вы передаёте значение туда, где ожидается, что оно будет вести себя как компонент, но у TypeScript нет способа подтвердить, что это действительно так.

// TypeScript doesn't know 'icon' is a valid component
interface ButtonProps {
  icon: object; // too vague
};

// So when you try this...
function Button({ icon: Icon }: ButtonProps) {
  return <Icon />;
}

// The above code will give you the error
// Error: JSX element type 'Icon' does not have any construct
// or call signatures

Решение: задайте тип динамическим компонентам с помощью React.ComponentType:

import { ComponentType } from 'react';

interface ButtonProps {
  icon: ComponentType;
};

function Button({ icon: Icon }: ButtonProps) {
  return (
    <button>
      <Icon />
    </button>
  );
}

// TypeScript now knows Icon is a valid component

Если этот компонент также принимает параметры, их можно описать явно:

interface IconProps {
  size?: number;
  color?: string;
};

interface ButtonProps {
  icon: ComponentType<IconProps>;
};

function Button({ icon: Icon }: ButtonProps) {
  return (
    <button>
      <Icon size={12} color="white" />
    </button>
  );
}

// So now the props are typed too

Полезным сокращением, которое стоит знать, является встроенный тип React PropsWithChildren. Он автоматически добавляет children?: ReactNode к любому интерфейсу параметров, вокруг которого он используется, тем самым избавляя от необходимости повторного объявления этого поля каждый раз:

import { PropsWithChildren } from 'react';

// Now instead of doing this
interface CardProps {
  title: string;
  children?: ReactNode;
};

// You can do this
type CardProps = PropsWithChildren<{ title: string }>;

// So with this, instead of explicitly typing children manually,
// you can use the above code

function Card({ title, children }: CardProps) {
  return (
    <div>
      <h1>{title}</h1>
      <div>{children}</div>
    </div>
  );
}

Проблема: отрисовка списков элементов

TypeScript налагает строгие правила относительно ключей в отображаемых списках, но большинство ошибок типов, с которыми вы столкнетесь здесь, на самом деле происходят из-за способа задания типов самих элементов, а не ключей.

// Items might be undefined, or item.id might not be a valid key type
function ItemList({ items }: { items: Item[] | undefined }) {
  return (
    <ul>
      {
        items.map(item => (
          <li key={item.id}>{item.name}</li>
        ))
      }
    </ul>
  );
}

// Error: Object is possibly 'undefined'

Решение: защищайтесь от значений undefined и убедитесь, что типы заданы правильно:

function ItemList({ items = [] }: { items?: Item[] }) {
  return (
    <ul>
      {
        items.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))
      }
    </ul>
  );
}

В заключение…

Ошибки TypeScript перестают казаться препятствиями, как только вы начинаете рассматривать их как подсказки. Это происходит в тот момент, когда вы перестаете реагировать со словами «Уф, опять это» и вместо этого начинаете спрашивать: «Что на самом деле пытается мне сказать TypeScript?»

Ошибки, рассматриваемые в этом руководстве, — это те, с которыми вы будете сталкиваться постоянно в процессе работы с React и TypeScript. То, что отличает разработчика, постоянно сталкивающегося с трудностями из-за системы типов, от того, кто работает с ней без проблем, обычно сводится лишь к умению распознавать шаблоны, и ничего более. На данный момент вы уже знакомы с этими шаблонами.