Skip to content

docs: move to documentation website #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 22, 2024
Merged

docs: move to documentation website #119

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 8 additions & 164 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<h1 align="center">
<a href="https://reactnative.dev/">
<a href="https://callstack.github.io/react-native-visionos-docs">
React Native visionOS
</a>
</h1>
Expand All @@ -13,175 +13,19 @@ React Native visionOS allows you to write visionOS with full support for platfor

![Screenshot](https://github.com/callstack/react-native-visionos/assets/52801365/0fcd5e5f-628c-49ef-84ab-d1d4675a011a)

## How is it different from running app in compatibility mode?
## 🎉 Building your first spatial React Native app
Follow the [Getting Started](https://callstack.github.io/react-native-visionos-docs/getting-started/create-first-app) guide. If you wish to get started quickly, you can utilize this command:

React Native visionOS unlocks full capabilities of the platform, giving your app transparent look that feels right at home next to other visionOS apps. It allows you to leverage the power of `ImmersiveSpace`s and multi-window apps.

Side by side comparison of running the same app: React Native visionOS vs React Native iOS (Compatibility mode).

https://github.com/callstack/react-native-visionos/assets/52801365/dd5d6351-3843-4f4a-ae67-541c068ac7be

> [!CAUTION]
> This project is still at an early stage of development and is not ready for production use.

## New project creation

1. Make sure you have a [proper development environment setup](https://reactnative.dev/docs/environment-setup)
2. Download the latest Xcode (at least 15.2).
3. Install visionOS simulator runtime.
4. Install the latest version of CMake (at least v3.28.0).
5. Initialize the project using this command:

```
```sh
npx @callstack/react-native-visionos@latest init YourApp
```
6. Next, go to `YourApp/visionos` folder and run following commands to install Pods:
```

```
bundle install
bundle exec pod install
```

7. Now you can run `yarn visionos`
8. (Optional) you also can open project using Xcode (`xed YourApp/visionos/YourApp.xcworkspace`).
- Build the app by clicking the "Run" button in Xcode.

## Platform guidelines

We suggest you read [Human Interface Guidelines for visionOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos) when creating visionOS apps.

It's important not to cover the translucent background with a solid color, as it helps to ground apps and make them feel like part of the environment.

## API Reference

### App entry point
React Native visionOS uses SwiftUI lifecycle. The app entry point is now `App.swift` file (by default it is `main.m`). This change allows us to use full capabilities of the visionOS SDK.

Here is an example from the template:
```swift
// App.swift
@main
struct HelloWorldApp: App {
@UIApplicationDelegateAdaptor var delegate: AppDelegate

var body: some Scene {
RCTMainWindow(moduleName: "HelloWorld")
}
}
```

We are using `@UIApplicationDelegateAdaptor`, a property wrapper that allows us to use familiar `AppDelegate` in SwiftUI life cycle.
## 📖 Documentation

`AppDelegate` extends `RCTAppDelegate` which does most of React Native initialization.

### Hover effect API
This is a prop on `<View />` component allowing to add hover effect. It's applied to all Touchable and Pressable components by default.

If you want to customize it you can use the `visionos_hoverEffect` prop, like so:

```tsx
<TouchableOpacity visionos_hoverEffect="lift">
<Text>Click me</Text>
</TouchableOpacity>
```

The available options are: `lift` or `highlight`.

### `XR` API (_nightly_)
Manage Immersive Experiences.

#### Methods
**`requestSession`**
```js
requestSession: (sessionId?: string) => Promise<void>
```
Opens a new [`ImmersiveSpace`](https://developer.apple.com/documentation/swiftui/immersive-spaces) given it's unique `Id`.

**`endSession`**
```js
endSession: () => Promise<void>
```
Closes currently open `ImmersiveSpace`.

#### Constants
**`supportsMultipleScenes`**
```js
supportsMultipleScenes: boolean
```
A Boolean value that indicates whether the app may display multiple scenes simultaneously. Returns the value of `UIApplicationSupportsMultipleScenes` key from `Info.plist`.

### Example Usage

1. Set `UIApplicationSupportsMultipleScenes` to `true` in `Info.plist`:
```diff
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationPreferredDefaultSceneSessionRole</key>
<string>UIWindowSceneSessionRoleApplication</string>
<key>UIApplicationSupportsMultipleScenes</key>
- <false/>
+ <true/>
<key>UISceneConfigurations</key>
<dict/>
</dict>
</dict>
</plist>

```


1. Inside `App.swift` add new `ImmersiveSpace`:
```diff
@main
struct HelloWorldApp: App {
@UIApplicationDelegateAdaptor var delegate: AppDelegate
+ @State private var immersionLevel: ImmersionStyle = .mixed

var body: some Scene {
RCTMainWindow(moduleName: "HelloWorldApp")
+ ImmersiveSpace(id: "TestImmersiveSpace") {
+ // RealityKit content goes here
+ }
+ .immersionStyle(selection: $immersionLevel, in: .mixed, .progressive, .full)
}
}
```
For more information about `ImmersiveSpace` API refer to [Apple documentation](https://developer.apple.com/documentation/swiftui/immersive-spaces).

In the above example we set `ImmersiveSpace` id to `TestImmersiveSpace`.

Now in our JS code, we can call:

```js
import {XR} from "@callstack/react-native-visionos"
//...
const openXRSession = async () => {
try {
if (!XR.supportsMultipleScenes) {
Alert.alert('Error', 'Multiple scenes are not supported');
return;
}
await XR.requestSession('TestImmersiveSpace'); // Pass the same identifier from `App.swift`
} catch (e) {
Alert.alert('Error', e.message);
}
};

const closeXRSession = async () => {
await XR.endSession();
};
```
> [!CAUTION]
> Opening an `ImmersiveSpace` can fail in this secarios:
> - `ImmersiveSpace` is not declared.
> - `UIApplicationSupportsMultipleScenes` is set to `false`.
> - User cancels the request.
The full documentation for React Native visionOS can be found on our [website](https://callstack.github.io/react-native-visionos-docs).

For a full example usage, refer to [`XRExample.js`](https://github.com/callstack/react-native-visionos/blob/main/packages/rn-tester/js/examples/XR/XRExample.js).
The source for the React Native visionOS documentation and website is hosted on a separate repo, @callstack/react-native-visionos-docs.

## Contributing

Expand Down