Preparing for react-native breaking changes

This commit is contained in:
SheetJS 2024-12-22 21:27:22 -05:00
parent 93c8689285
commit d378da011c
8 changed files with 173 additions and 59 deletions

@ -942,13 +942,6 @@ of the React Native documentation before testing the demo.
:::
:::caution pass
For Android testing, React Native requires Java 11. It will not work with
current Java releases.
:::
:::danger pass
There are a number of potential pitfalls.
@ -964,10 +957,10 @@ any issues not mentioned in the demo page.**
Create a new project by running the following commands in the Terminal:
<CodeBlock language="bash">{`\
npx -y react-native@0.73.6 init SheetJSPres --version="0.73.6"
npx -y @react-native-community/cli@15 init SheetJSPres --version="0.76.5"
cd SheetJSPres
\n\
npm i -S https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz react-native-blob-util@0.19.8`}
npm i -S https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz react-native-blob-util@0.21.2`}
</CodeBlock>
Save the following to `App.tsx` in the project:
@ -1060,10 +1053,10 @@ npx react-native start
Once Metro is ready, it will display the commands:
```
r - reload the app
d - open developer menu
i - run on iOS
a - run on Android
r - reload app
d - open Dev Menu
j - open DevTools
```
Press `a` to run on Android. The app will launch in the emulator.

@ -966,7 +966,7 @@ uses the native `FlatList` component.
Create a new project by running the following commands in the Terminal:
<CodeBlock language="bash">{`\
npx react-native@0.72.4 init SheetJSSL --version="0.72.4"
npx -y @react-native-community/cli@15 init SheetJSSL --version="0.76.5"
cd SheetJSSL
npm i -S https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
@ -1042,10 +1042,10 @@ npx react-native start
Once Metro is ready, it will display the commands:
```
r - reload the app
d - open developer menu
i - run on iOS
a - run on Android
r - reload app
d - open Dev Menu
j - open DevTools
```
Press `a` to run on Android.
@ -1066,6 +1066,12 @@ This demo runs in iOS and requires a Macintosh computer with Xcode installed.
:::
The native component must be linked:
```bash
cd ios; pod install; cd ..
```
Test the app in the iOS simulator:
```bash

@ -614,7 +614,7 @@ On Arch Linux-based platforms including the Steam Deck, the install may fail:
error: externally-managed-environment
```
It is recommended to use a virtual environment for Polars.
It is recommended to use a virtual environment.
`venv` must be installed through the system package manager:

@ -237,7 +237,7 @@ This demo was tested in the following environments:
| iOS 17.4 | iPhone 15 Pro Max | `0.73.6` | `darwin-x64` | 2024-03-13 |
| Android 34 | Pixel 3a | `0.74.2` | `darwin-arm` | 2024-06-20 |
| iOS 17.5 | iPhone SE (3rd gen) | `0.74.2` | `darwin-arm` | 2024-06-20 |
| Android 34 | Pixel 3a | `0.73.5` | `win10-x64` | 2024-03-05 |
| Android 35 | Pixel 9 | `0.76.5` | `win11-x64` | 2024-12-22 |
| Android 34 | Pixel 3a | `0.73.7` | `linux-x64` | 2024-04-29 |
:::
@ -277,9 +277,19 @@ export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
1) Create project:
```bash
npx -y react-native@0.74.2 init SheetJSRNFetch --version="0.74.2"
npx -y @react-native-community/cli@15 init SheetJSRNFetch --version="0.76.5"
```
:::info pass
Older versions of this demo used the `react-native` package. The `init` command
was officially deprecated.
React Native now recommends using `@react-native-community/cli`. The versioning
scheme is fundamentally different from `react-native`.[^6]
:::
2) Install shared dependencies:
<CodeBlock language="bash">{`\
@ -297,7 +307,7 @@ curl -LO https://docs.sheetjs.com/reactnative/App.tsx
**Android Testing**
4) Install or switch to Java 17[^6]
4) Install or switch to Java 17[^7]
5) Start the Android emulator:
@ -337,6 +347,25 @@ This error can be resolved by installing and switching to the requested version.
:::caution pass
When this demo was last tested on Windows 11, there was a Gradle error
mentioning a "temporary workspace":
```
> java.io.UncheckedIOException: Could not move temporary workspace (C:\Users\sheetjs\Documents\SheetJSRNFetch\android\.gradle\8.10.2\dependencies-accessors\569c8b261a8a714d7731d5f568e0e5c05babae10-4756c477-c60a-4328-ba8c-e12cc53b4ed0) to immutable location (C:\Users\sheetjs\Documents\SheetJSRNFetch\android\.gradle\8.10.2\dependencies-accessors\569c8b261a8a714d7731d5f568e0e5c05babae10)
```
**This is a known bug in the version of Gradle used by React Native 0.76.5!**
The Gradle version should be set to `8.11.1` in `gradle-wrapper.properties`:
```text title="android/gradle/wrapper/gradle-wrapper.properties (change line)"
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
```
:::
:::caution pass
When this demo was last tested on Linux, the process failed to launch the emulator:
<pre>
@ -460,7 +489,7 @@ If the device asks to trust the computer, tap "Trust" and enter the passcode.
14) Close any Android / iOS emulators.
15) Enable developer code signing certificates[^7].
15) Enable developer code signing certificates[^8].
<details open>
<summary><b>Enabling Code Signing</b> (click to show)</summary>
@ -660,10 +689,10 @@ for accessing data and are subject to change in future platform versions.
iOS applications typically require two special settings in `Info.plist`:
- `UIFileSharingEnabled`[^8] allows users to use files written by the app. A
- `UIFileSharingEnabled`[^9] allows users to use files written by the app. A
special folder will appear in the "Files" app.
- `LSSupportsOpeningDocumentsInPlace`[^9] allows the app to open files without
- `LSSupportsOpeningDocumentsInPlace`[^10] allows the app to open files without
creating a local copy.
Both settings must be set to `true`:
@ -1007,7 +1036,7 @@ This demo was tested in the following environments:
|:-----------|:------------------|:---------|:-------------|:-----------|
| Android 34 | Pixel 3a | `0.73.6` | `darwin-x64` | 2024-03-31 |
| iOS 17.4 | iPhone 15 Pro Max | `0.73.6` | `darwin-x64` | 2024-03-31 |
| Android 34 | Pixel 3a | `0.73.6` | `win10-x64` | 2024-03-31 |
| Android 35 | Pixel 9 | `0.76.5` | `win11-x64` | 2024-03-31 |
| Android 34 | Pixel 3a | `0.73.6` | `linux-x64` | 2024-03-31 |
:::
@ -1016,7 +1045,7 @@ This demo was tested in the following environments:
There are many moving parts and pitfalls with React Native apps. It is strongly
recommended to follow the official React Native tutorials for iOS and Android
before approaching this demo.[^10] Details including Android Virtual Device
before approaching this demo.[^11] Details including Android Virtual Device
configuration are not covered here.
:::
@ -1028,7 +1057,7 @@ This example tries to separate the library-specific functions.
1) Create project:
```bash
npx react-native init SheetJSRN --version="0.73.6"
npx -y @react-native-community/cli@15 init SheetJSRN --version="0.76.5"
```
On macOS, if prompted to install `CocoaPods`, press `y`.
@ -1039,7 +1068,7 @@ On macOS, if prompted to install `CocoaPods`, press `y`.
cd SheetJSRN
curl -LO https://docs.sheetjs.com/logo.png
npm i -S https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
npm i -S react-native-table-component@1.2.2 react-native-document-picker@9.1.1`}
npm i -S react-native-table-component@1.2.2 react-native-document-picker@9.3.1`}
</CodeBlock>
3) Download [`index.js`](pathname:///mobile/index.js) and replace:
@ -1060,18 +1089,37 @@ The app should look like the following screenshot:
:::caution pass
When this demo was last tested on Windows, the build failed with an error:
In some test runs on Windows, the build failed with an error:
```
> Failed to apply plugin 'com.android.internal.application'.
> Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
```
Java 17 must be installed[^11] and the `JAVA_HOME` environment variable must
Java 17 must be installed[^12] and the `JAVA_HOME` environment variable must
point to the Java 17 location.
:::
:::caution pass
When this demo was last tested on Windows 11, there was a Gradle error
mentioning a "temporary workspace":
```
> java.io.UncheckedIOException: Could not move temporary workspace (C:\Users\sheetjs\Documents\SheetJSRNFetch\android\.gradle\8.10.2\dependencies-accessors\569c8b261a8a714d7731d5f568e0e5c05babae10-4756c477-c60a-4328-ba8c-e12cc53b4ed0) to immutable location (C:\Users\sheetjs\Documents\SheetJSRNFetch\android\.gradle\8.10.2\dependencies-accessors\569c8b261a8a714d7731d5f568e0e5c05babae10)
```
**This is a known bug in the version of Gradle used by React Native 0.76.5!**
The Gradle version should be set to `8.11.1` in `gradle-wrapper.properties`:
```text title="android/gradle/wrapper/gradle-wrapper.properties (change line)"
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
```
:::
Stop the dev server and close the React Native Metro NodeJS window.
**File Integration**
@ -1084,7 +1132,7 @@ Stop the dev server and close the React Native Metro NodeJS window.
Install `react-native-blob-util` dependency:
```bash
npm i -S react-native-blob-util@0.19.8
npm i -S react-native-blob-util@0.21.2
```
Add the highlighted lines to `index.js`:
@ -1132,7 +1180,7 @@ const make_width = ws => {
Install `react-native-file-access` dependency:
```bash
npm i -S react-native-file-access@3.0.7
npm i -S react-native-file-access@3.1.1
```
Add the highlighted lines to `index.js`:
@ -1187,6 +1235,21 @@ If prompted to install Expo CLI integration, choose No.
:::
:::info pass
On Windows, `npx install-expo-modules` will throw errors related to CocoaPods:
```
Uncaught Error CocoaPodsError: Command `pod install` failed.
└─ Cause: spawn pod ENOENT
'pod' is not recognized as an internal or external command,
operable program or batch file.
```
These errors can be ignored.
:::
Add the highlighted lines to `index.js`:
```js title="index.js"
@ -1559,14 +1622,15 @@ Swipe left until the "Numbers" app icon appears and tap the app icon.
The Numbers app will load the spreadsheet, confirming that the file is valid.
[^1]: Follow the ["React Native CLI Quickstart"](https://reactnative.dev/docs/environment-setup) and select the appropriate "Development OS".
[^1]: Follow the ["Set Up Your Environment" guide](https://reactnative.dev/docs/set-up-your-environment) and select the appropriate "Development OS".
[^2]: See ["Array of Arrays" in the API reference](/docs/api/utilities/array#array-of-arrays)
[^3]: See ["Array Output" in "Utility Functions"](/docs/api/utilities/array#array-output)
[^4]: See ["Array of Arrays Input" in "Utility Functions"](/docs/api/utilities/array#array-of-arrays-input)
[^5]: React-Native commit [`5b597b5`](https://github.com/facebook/react-native/commit/5b597b5ff94953accc635ed3090186baeecb3873) added the final piece required for `fetch` support. It is available in official releases starting from `0.72.0`.
[^6]: When the demo was last tested, the Temurin distribution of Java 17 was installed through the macOS Brew package manager by running `brew install temurin17`. [Direct downloads are available at `adoptium.net`](https://adoptium.net/temurin/releases/?version=17)
[^7]: See ["Running On Device"](https://reactnative.dev/docs/running-on-device) in the React Native documentation
[^8]: See [`UIFileSharingEnabled`](https://developer.apple.com/documentation/bundleresources/information_property_list/uifilesharingenabled) in the Apple Developer Documentation.
[^9]: See [`LSSupportsOpeningDocumentsInPlace`](https://developer.apple.com/documentation/bundleresources/information_property_list/lssupportsopeningdocumentsinplace) in the Apple Developer Documentation.
[^10]: Follow the ["React Native CLI Quickstart"](https://reactnative.dev/docs/environment-setup) for Android (and iOS, if applicable)
[^11]: See the [JDK Archive](https://jdk.java.net/archive/) for Java 17 JDK download links.
[^6]: See [the compatibility table](https://github.com/react-native-community/cli) in the CLI project repository to determine which version of `@react-native-community/cli` is required for a given `react-native` version.
[^7]: When the demo was last tested, the Temurin distribution of Java 17 was installed through the macOS Brew package manager by running `brew install temurin17`. [Direct downloads are available at `adoptium.net`](https://adoptium.net/temurin/releases/?version=17)
[^8]: See ["Running On Device"](https://reactnative.dev/docs/running-on-device) in the React Native documentation
[^9]: See [`UIFileSharingEnabled`](https://developer.apple.com/documentation/bundleresources/information_property_list/uifilesharingenabled) in the Apple Developer Documentation.
[^10]: See [`LSSupportsOpeningDocumentsInPlace`](https://developer.apple.com/documentation/bundleresources/information_property_list/lssupportsopeningdocumentsinplace) in the Apple Developer Documentation.
[^11]: Follow the ["React Native CLI Quickstart"](https://reactnative.dev/docs/environment-setup) for Android (and iOS, if applicable)
[^12]: See the [JDK Archive](https://jdk.java.net/archive/) for Java 17 JDK download links.

@ -46,10 +46,10 @@ This demo was tested in the following environments:
| OS and Version | Architecture | RN Platform | Date |
|:---------------|:-------------|:------------|:-----------|
| Windows 11 | `win11-x64` | `v0.74.6` | 2024-05-28 |
| Windows 11 | `win11-x64` | `v0.75.11` | 2024-12-22 |
| Windows 11 | `win11-arm` | `v0.74.5` | 2024-05-25 |
| MacOS 14.7 | `darwin-x64` | `v0.75.13` | 2024-10-26 |
| MacOS 14.5 | `darwin-arm` | `v0.73.30` | 2024-05-28 |
| MacOS 14.5 | `darwin-arm` | `v0.75.16` | 2024-12-22 |
:::
@ -419,17 +419,34 @@ iex (New-Object System.Net.WebClient).DownloadString('https://aka.ms/rnw-vs2022-
If any step fails to install, open the dependencies page and expand "Manual
setup instructions" to find instructions for manual installation.
:::note pass
Even though React Native for Windows recommends enabling "Developer Mode", it is
not a requirement for this demo.
:::
</details>
### Project Setup
1) Create a new project using React Native `0.74.1`:
1) Create a new project using React Native `0.75.4`:
```bash
npx react-native init SheetJSWin --template react-native@0.74.1
npx -y @react-native-community/cli@14 init SheetJSWin --version="0.75.4"
cd SheetJSWin
```
:::info pass
Older versions of this demo used the `react-native` package. The `init` command
was officially deprecated.
React Native now recommends using `@react-native-community/cli`. The versioning
scheme is fundamentally different from `react-native`.[^5]
:::
2) Create the Windows part of the application:
<Tabs groupId="rnwlang">
@ -646,33 +663,31 @@ Native for macOS required React Native `0.71`.
**The official documentation is out of date.**
There exist official `react-native-macos` releases compatible with RN `0.73`
There exist official `react-native-macos` releases compatible with RN `0.75`
:::
0) Follow the "Setting up the development environment"[^5] guide in the React
0) Follow the "Setting up the development environment"[^6] guide in the React
Native documentation for "React Native CLI Quickstart" + "macOS" + "iOS".
### Project Setup
1) Create a new React Native project using React Native `0.73`:
1) Create a new React Native project using React Native `0.75.4`:
```bash
npx -y @react-native-community/cli init SheetJSmacOS --version 0.75
npx -y @react-native-community/cli init SheetJSmacOS --version 0.75.4
cd SheetJSmacOS
```
If prompted to install CocoaPods, type `Y`.
:::note pass
:::info pass
For older versions of React Native, the `react-native` package included the CLI:
Older versions of this demo used the `react-native` package. The `init` command
was officially deprecated.
```bash
npx -y react-native init SheetJSmacOS --template react-native@^0.73.0
```
This approach is deprecated as of React Native `0.75`.
React Native now recommends using `@react-native-community/cli`. The versioning
scheme is fundamentally different from `react-native`.[^5]
:::
@ -721,9 +736,9 @@ npx react-native run-macos
Close the running app from the dock and close the Metro terminal window.
:::danger pass
:::caution pass
When the demo was last tested, the app failed with a warning
In some test runs, the app failed with a warning
> No bundle URL present.
@ -793,7 +808,7 @@ A) Copy the highlighted line and paste under `/* Begin PBXBuildFile section */`:
/* Begin PBXBuildFile section */
// highlight-next-line
4717DC6A28CC499A00A9BE56 /* RCTDocumentPicker.m in Sources */ = {isa = PBXBuildFile; fileRef = 4717DC6928CC499A00A9BE56 /* RCTDocumentPicker.m */; };
3EBD77615057B69A2488153F /* libPods-SheetJSmacOS-macOS.a in Frameworks */ = {isa = PBXBuildFile; fileRef = C28E160785274A8AF9074969 /* libPods-SheetJSmacOS-macOS.a */; };
2C5F4006FF53E87968033016 /* libPods-SheetJSmacOS-macOS.a in Frameworks */ = {isa = PBXBuildFile; fileRef = CC1DD40D19AD16D57CAA4CB6 /* libPods-SheetJSmacOS-macOS.a */; };
```
:::
@ -988,6 +1003,39 @@ If there are no instances, the app path can be found in the `DerivedData` folder
find ~/Library/Developer/Xcode/DerivedData -name SheetJSmacOS.app | grep Release
```
:::caution pass
During the last test, `xcodebuild` failed. Scrolling through the log reveals:
```
Welcome to Metro v0.80.12
Fast - Scalable - Integrated
node:events:497
throw er; // Unhandled 'error' event
^
Error: EMFILE: too many open files, watch
at FSWatcher._handle.onchange (node:internal/fs/watchers:207:21)
```
The file descriptor limits must be increased[^7].
```bash
sudo sysctl -w kern.maxfiles=10485760
sudo sysctl -w kern.maxfilesperproc=1048576
```
After making this change, forcefully reset `watchman`:
```bash
watchman shutdown-server
watchman watch-del-all
```
:::
15) Run the release app:
```bash
@ -1003,4 +1051,6 @@ The app will refresh and display the data from the file.
[^2]: See ["Array of Arrays" in the API reference](/docs/api/utilities/array#array-of-arrays)
[^3]: See ["Array Output" in "Utility Functions"](/docs/api/utilities/array#array-output)
[^4]: See ["Turbo Native Modules"](https://reactnative.dev/docs/the-new-architecture/pillars-turbomodules) in the React Native documentation.
[^5]: See ["Setting up the development environment"](https://reactnative.dev/docs/environment-setup) in the React Native documentation. Select the "React Native CLI Quickstart" tab and choose the Development OS "macOS" and the Target OS "iOS".
[^5]: See [the compatibility table](https://github.com/react-native-community/cli) in the CLI project repository to determine which version of `@react-native-community/cli` is required for a given `react-native` version.
[^6]: See ["Setting up the development environment"](https://reactnative.dev/docs/environment-setup) in the React Native documentation. Select the "React Native CLI Quickstart" tab and choose the Development OS "macOS" and the Target OS "iOS".
[^7]: See ["macOS File Descriptor Limits"](https://facebook.github.io/watchman/docs/install.html#mac-os-file-descriptor-limits) in the `watchman` docs for more details

@ -201,7 +201,7 @@ flowchart LR
pwd
```
This folder is typically `MATLAB` with the `Documents` folder for the account.
This folder is typically `MATLAB` within the `Documents` folder for the account.
1) Open a new macOS Terminal or Windows PowerShell window.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 102 KiB

After

Width:  |  Height:  |  Size: 20 KiB

@ -6,7 +6,8 @@
"alex": {
"allow": [
"host-hostess",
"hook", "hooks",
"hook",
"hooks",
"chinese",
"special",
"simple",