paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

apply requested changes

Browse Source 
Signed-off-by: Paul Schultz <pschultz@pobox.com>
This commit is contained in:
Paul Schultz
2025-01-30 17:06:06 -06:00
parent b45d558d09
commit d92abd3b32
2 changed files with 18 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/jsx-transform-migration.md
+16 -3
View File
@@ -4,15 +4,28 @@ title: Transitioning to the New JSX Transform
description: A guide to migrating your project to the New JSX Transform
---
The Backstage core libraries are in the process of deprecating React 16 and evaluating the adoption of React 19. In React 19, the [New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html), introduced in September 2020, is now [mandatory](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#installing). This requires a modification in how React is imported into components to ensure compatibility with React 19.
Backstage core libraries currently support React 18. We are actively evaluating the upgrade to React 19, which introduces significant changes, including making the [New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) mandatory.
## What this means for you
- **If you are already using the New JSX Transform:** You are not impacted by this change, regardless of your React version (17, 18, or when 19 becomes available for Backstage).
- **If you are NOT using the New JSX Transform (likely if you're importing React like `import React from 'react'`):** You will need to adopt it before upgrading to React 19. This typically involves changing your imports, as the New JSX Transform doesn't require importing the entire React namespace to use JSX. This is recommended even on React 17 or 18, as it was a change introduced with React 17. Although a best practice since React 17, Backstage did not adopt this transform when it upgraded.
## Action Required
While upgrading to React 19 within Backstage is not yet officially supported, it's recommended to proactively adopt the New JSX Transform if you haven't already. This will ensure a smoother transition when React 19 support is introduced and improve compatibility with the current React ecosystem.
## Timeline
We are currently evaluating React 19 and will provide further guidance on the upgrade path and timelines soon. For now, you can prepare by adopting the New JSX Transform.
## Migration Process
### Using the Codemod
The codemod referenced in the [Introducing the New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) article is no longer functional. However, we have identified a working solution detailed below.
While a codemod for the New JSX Transform was originally introduced in the [Introducing the New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) article, it is no longer functional. A working solution, inspired by the original, is detailed below:
1. **Create a transformation file**
1. **Create the transform file**
Create a file named `transform.js` in the root directory of your Backstage project.
docs/tutorials/react18-migration.md
+2 -2
View File
@@ -20,7 +20,7 @@ _Before diving in, this is a heads-up that for large projects this can be a tric
#### Backstage Instance
To migrate a Backstage instance to React 18, follow these three steps:
To migrate a Backstage instance to React 18, follow these steps:
1. Modify the `resolutions` section in your root `package.json` to reference the latest versions of `@types/react` and `@types/react-dom`:
@@ -120,7 +120,7 @@ Be sure to update your lockfile after modifying your `package.json` files.
When upgrading to React 18 you are likely to see a fair number of TypeScript type errors. A summary of the breaking changes can be found in the [Pull Request that introduced them](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/56210). A codemod is also provided to help with the migration.
Run `yarn tsc:full` to access the damage.
Run `yarn tsc:full` to assess the damage.
The good news is that these errors can be fixed while still staying on React 17. If you have a large number of errors to fix you can address as few or many is you like at a time and merge them into your main branch **without** the version bumps from step 1. This lets you gradually migrate the types in your project while not yet fully moving over to React 18. Once all type breakages are fixed you can move on to the next step of migrating tests.