새 JSX Transform으로 전환

원문 보기 위키 갱신 2026.10.07

새 JSX Transform으로 전환 (Transitioning to the New JSX Transform)

Backstage 핵심 라이브러리는 현재 React 18을 지원합니다. 우리는 React 19로의 업그레이드를 적극적으로 평가하고 있으며, 여기에는 New JSX Transform을 필수로 만드는 것을 포함한 중요한 변경이 도입됩니다.

출처: 문서

본문

이것이 당신에게 의미하는 것 (What this means for you)

이미 New JSX Transform을 사용 중이라면: React 버전(17, 18, 또는 19가 Backstage에 제공될 때)과 관계없이 이 변경의 영향을 받지 않습니다.
New JSX Transform을 사용하지 않는다면(import React from 'react'처럼 React를 가져오는 경우일 가능성이 높음): React 19로 업그레이드하기 전에 채택해야 합니다. New JSX Transform은 JSX를 사용하기 위해 전체 React 네임스페이스를 가져올 필요가 없으므로, 이는 일반적으로 임포트를 변경하는 것을 수반합니다. 이는 React 17에서 도입된 변경이므로 React 17 또는 18에서도 권장됩니다. React 17 이후 모범 사례였지만 Backstage는 업그레이드할 때 이 변환을 채택하지 않았습니다.

필요한 조치 (Action Required)

Backstage 내에서 React 19로 업그레이드하는 것이 아직 공식적으로 지원되지는 않지만, 아직 하지 않았다면 New JSX Transform을 사전에 채택하는 것이 좋습니다. 이렇게 하면 React 19 지원이 도입될 때 더 매끄러운 전환이 보장되고 현재 React 생태계와의 호환성이 향상됩니다.

타임라인 (Timeline)

현재 React 19를 평가 중이며 곧 업그레이드 경로와 타임라인에 대한 추가 지침을 제공할 것입니다. 지금은 New JSX Transform을 채택하여 준비할 수 있습니다.

마이그레이션 과정 (Migration Process)

React 임포트 업데이트 (Updating React Imports)

import * as React from 'react'와 import React from 'react'의 모든 발생을 다음과 같은 명명된 임포트로 찾아 바꿉니다.

import { useState, useEffect } from 'react';

호환성 이유로 기본 React 임포트를 보존해야 한다면 다음을 사용할 수 있습니다.

import { default as React } from 'react';

이 과정을 간소화하려면 자동화된 codemod 사용을 고려하세요.

구성 파일 업데이트 (Updating Configuration Files)

@backstage/cli를 사용할 때 호환성을 보장하려면 tsconfig.json을 새 JSX 변환을 사용하도록 업데이트해야 합니다.

TypeScript 구성 (TSConfig)

tsconfig.json의 compilerOptions.jsx 설정을 react-jsx로 업데이트합니다. 이 파일은 일반적으로 루트 디렉터리에 있습니다.

{  "extends": "@backstage/cli/config/tsconfig.json",  ...  "compilerOptions": {    "jsx": "react",    "jsx": "react-jsx"  }}

향후 React 17이 완전히 폐기되면 이 설정은 preserve로 변경될 것입니다.

`compilerOptions.jsx` 값 설명

react 모드: 이 모드는 JSX를 React.createElement 호출로 변환하여 React가 직접 사용할 수 있게 합니다. 코드는 별도의 JSX 변환 단계가 필요하지 않으며 출력 파일은 .js 확장자를 사용합니다.
react-jsx 모드: React 17에서 도입된 이 모드는 JSX 변환을 자동으로 처리하여 각 파일에서 React를 가져올 필요 없이 JSX를 사용할 수 있게 합니다.
preserve 모드: 이 옵션은 JSX 코드를 그대로 두고 출력 파일에 직접 포함합니다. 나중에 Babel 같은 다른 도구로 JSX를 처리할 계획일 때 유용합니다. 결과 파일은 JSX의 존재를 나타내기 위해 .jsx 확장자를 사용합니다.

추가 리소스 (Additional Resources)

Introducing the New JSX Transform
React 19 Upgrade Guide

새 JSX Transform으로 전환