Ошибка JSX в TypeScript: флаг --jsx и как её исправить

«Cannot use JSX unless the '--jsx' flag is provided» — что это за зверь?

Представьте: вы с энтузиазмом пишете своё первое React-приложение на TypeScript. Код выглядит идеально, компоненты продуманы, настроение боевое. Вы запускаете компиляцию — и вдруг видите это холодное, пугающее сообщение:

Cannot use JSX unless the '--jsx' flag is provided.

Знакомо? Не переживайте, вы не одиноки. Эта ошибка — один из самых популярных вопросов на Stack Overflow с тысячами просмотров. Но, как и любая загадка, она имеет простое и элегантное решение. В этой статье мы не просто исправим ошибку, но и поймём, почему она возникает и как настроить TypeScript для работы с JSX раз и навсегда.

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

Почему TypeScript ругается на JSX?

Давайте разберёмся с природой этой ошибки. TypeScript — это строгий язык, который не понимает HTML-подобный синтаксис JSX по умолчанию. Когда вы пишете:

const element = <h1>Hello, World!</h1>;

TypeScript видит не знакомый код, а нечто чужеродное. Чтобы объяснить компилятору, что эти угловые скобки — не ошибка, а часть вашего React-компонента, нужно явно указать флаг --jsx. Это как дать переводчика TypeScript: «Слушай, эти конструкции — валидный JSX, не трогай их, а обработай правильно».

Ошибка возникает в трёх типичных случаях:

• Новый проект — вы забыли настроить tsconfig.json для работы с React;
• Миграция с JavaScript — вы переводите проект на TypeScript, но не обновили конфигурацию;
• Использование .tsx файлов — вы создали файл с расширением .tsx, но компилятор не знает, что с ним делать.

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

Пошаговое решение: настройка tsconfig.json

Самый правильный и рекомендуемый способ — добавить настройку JSX в ваш tsconfig.json. Этот файл — мозг вашего TypeScript-проекта. Именно здесь мы скажем компилятору, как обрабатывать JSX.

Шаг 1: Откройте tsconfig.json

Найдите файл tsconfig.json в корне вашего проекта. Если его нет — создайте. Это можно сделать командой:

npx tsc --init

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

Шаг 2: Добавьте опцию jsx

Внутри объекта compilerOptions добавьте (или раскомментируйте) строку:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    // остальные настройки...
  }
}

Обратите внимание: значение "react-jsx" — это современный стандарт для React 17+ и React 18. Если вы используете старую версию React (до 17), можно указать "react". Но я настоятельно рекомендую "react-jsx" — он производит более оптимизированный код и не требует импорта React в каждом файле.

Шаг 3: Сохраните и перезапустите компиляцию

После сохранения изменений ошибка должна исчезнуть. Запустите сборку заново:

npm run build
# или
npx tsc

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

Альтернативные способы: для продвинутых пользователей

Иногда нужно быстро проверить гипотезу или запустить однофайловый скрипт. В таких случаях можно использовать флаг командной строки:

npx tsc --jsx react-jsx app.tsx

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

Ещё один вариант — указать JSX-режим в jsconfig.json (для JavaScript-проектов). Но если вы пишете на TypeScript, лучше придерживаться tsconfig.json.

Разбираемся с режимами JSX в TypeScript

Чтобы чувствовать себя уверенно, давайте разберём все возможные значения опции jsx. Их несколько, и выбор зависит от вашего проекта:

• "react" — классический режим. Преобразует JSX в вызовы React.createElement. Требует импорта React в каждом файле.
• "react-jsx" — современный режим (рекомендуемый). Использует новый JSX transform из React 17+. Не требует импорта React.
• "react-jsxdev" — то же, что и react-jsx, но с дополнительной информацией для отладки в режиме разработки.
• "preserve" — сохраняет JSX без изменений. Полезно, если вы используете другой инструмент (например, Babel) для последующей обработки JSX.
• "react-native" — для React Native проектов.

Для 99% веб-проектов на React 17+ выбирайте "react-jsx". Это современно, быстро и удобно.

Живой пример: от ошибки к рабочему компоненту

Давайте посмотрим на реальный пример. Допустим, у вас есть файл App.tsx:

// App.tsx
const App = () => {
  return (
    <div>
      <h1>Привет, мир!</h1>
      <p>Это мой первый компонент на TypeScript</p>
    </div>
  );
};

export default App;

Без настройки jsx в tsconfig.json вы получите ту самую ошибку. После добавления "jsx": "react-jsx" код скомпилируется без проблем. Заметьте: нам даже не нужно импортировать React — современный JSX transform делает это автоматически.

Если вы используете старый подход (React < 17), добавьте импорт:

import React from 'react';

const App = () => {
  return (
    <div>
      <h1>Привет, мир!</h1>