diff --git a/lerna.json b/lerna.json index ac0657d..05a7434 100644 --- a/lerna.json +++ b/lerna.json @@ -2,9 +2,9 @@ "capacitorVersion": "6.0.0", "iosMinVersion": "13.0", "androidMinSdk": "22", - "rnMinVersion": "0.63.4", + "rnMinVersion": "0.74.2", "androidLiveUpdatesVersion": "0.5.3", - "rnVersion": "0.5.2", + "rnVersion": "0.7.0", "iosVersion": "0.11.0", "androidVersion": "0.10.0", "cliVersion": "0.3.1", diff --git a/website/docs/for-react-native/getting-started.md b/website/docs/for-react-native/getting-started.md index c537174..d88fe32 100644 --- a/website/docs/for-react-native/getting-started.md +++ b/website/docs/for-react-native/getting-started.md @@ -18,10 +18,11 @@ await register('YOUR_PORTAL_KEY_HERE'); ## Creating a Portal and Rendering It -Create a Portal and add it to the portal registry: +Create a PortalView in your view hierarchy: ```javascript -import { addPortal } from '@ionic/portals-react-native'; +import { PortalView } from '@ionic/portals-react-native'; + const helloPortal = { // A unique name to reference later name: 'hello', @@ -34,24 +35,8 @@ const helloPortal = { }, }; -await addPortal(helloPortal); -``` - -Create a PortalView in your view hierarchy: - -```javascript -import { PortalView } from '@ionic/portals-react-native'; - ; diff --git a/website/docs/for-react-native/guide.md b/website/docs/for-react-native/guide.md index 308d601..2c52f47 100644 --- a/website/docs/for-react-native/guide.md +++ b/website/docs/for-react-native/guide.md @@ -54,7 +54,7 @@ To add Portals to your React Native project, install it via NPM: ## Configure -After installing the dependency you need to register your copy of Ionic Portals at runtime. This works both offline and in production. You'll need to call [register(myApiKey)](https://react-native-ionic-portals.vercel.app/functions/register.html) before creating any Portals in your app. Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. To get an API Key, refer to the [Sign Up](#signup) section. +After installing the dependency you need to register your copy of Ionic Portals at runtime. This works both offline and in production. You'll need to call [register(myApiKey)](https://react-native-ionic-portals.vercel.app/functions/register.html) before rendering any Portals in your app. Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. To get an API Key, refer to the [Sign Up](#signup) section. ```javascript title=App.tsx import { register } from "@ionic/portals-react-native"; diff --git a/website/docs/for-react-native/how-to/define-api-in-typescript.md b/website/docs/for-react-native/how-to/define-api-in-typescript.md index 1645222..48033c3 100644 --- a/website/docs/for-react-native/how-to/define-api-in-typescript.md +++ b/website/docs/for-react-native/how-to/define-api-in-typescript.md @@ -118,8 +118,6 @@ After creating the Capacitor Plugin, add the Plugin to the Portal to use it. You will need to add the classpath to your custom plugin for Android and the Objective-C class name for iOS (the name provided in the @objc annotation in the example above): ```javascript -import { addPortal } from "@ionic/portals-react-native"; - const echoPortal = { name: "echoPortal", plugins: [ @@ -129,8 +127,6 @@ const echoPortal = { } ] }; - -addPortal(echoPortal); ``` ## Calling Your Plugin Code via the Web diff --git a/website/docs/for-react-native/how-to/pull-in-web-bundle.md b/website/docs/for-react-native/how-to/pull-in-web-bundle.md index da33e2b..bce37fd 100644 --- a/website/docs/for-react-native/how-to/pull-in-web-bundle.md +++ b/website/docs/for-react-native/how-to/pull-in-web-bundle.md @@ -13,8 +13,6 @@ In order to use web applications in your native applications, you'll need to pro Follow the [Android instructions](../../for-android/how-to/pull-in-web-bundle.md) and [iOS instructions](../../for-ios/how-to/pull-in-web-bundle.md) in your native applications. You should make the start directories the same between both platforms to avoid issues rendering a Portal. ```javascript -import { addPortal } from "@ionic/portals-react-native"; - const help = { name: "myPortalWebApp", }; diff --git a/website/docs/for-react-native/how-to/statically-define-portals.md b/website/docs/for-react-native/how-to/statically-define-portals.md index 4933cdb..1bcfaeb 100644 --- a/website/docs/for-react-native/how-to/statically-define-portals.md +++ b/website/docs/for-react-native/how-to/statically-define-portals.md @@ -1,6 +1,6 @@ --- title: Static Portals Configuration File -sidebar_label: Statically Configure Portals +sidebar_label: Statically Register Portals --- An additional configuration method is now included to support a JSON configuration file to configure Portals on application start. The JSON file must be named `portals.config.json` and be placed in the application root on iOS and `assets` root on Android. @@ -19,99 +19,14 @@ type PortalConfig = { // This can be omitted if the `register` function is called before // attempting to render any portals in code. registrationKey?: string; - portals: []Portal; } - -// The Portal and LiveUpdate types are the same as their corresponding types -// in the library. -type Portal = { - // The name of the Portal to be referenced. Must be unique. - name: string; - // Any CapcitorPlugins to register with the Portal. - plugins?: []CapacitorPlugin; - // The root directory of the web application relative to Bundle.main - // on iOS and src/main/assets on Android. If omitted, `name` is used. - startDir?: string; - // Any data needed at initial render when a portal is loaded. If this - // data is not statically known, it can be added dynamically on render - // through `initialContext` props on `PortalView` and omitted from the - // configuration. - initialContext?: { - [key: string]: any; - }; - // The name of the initial file to load. If omitted, `index.html` is used. - // This field is useful for scenarios when using an SSG like Next.js and - // the entrypoint for the Portal is not the entrypoint for the overall - // application. - index?: string; - // The live update configuration if the portal is configured for remote - // updates. - liveUpdate?: LiveUpdateConfig -}; - -type LiveUpdateConfig = { - // The AppFlow application ID - appId: string; - // The AppFlow distribution channel - channel: string; - // Whether to perform a sync when the LiveUpdateConfig is registered. - // If you want to manually control when a LiveUpdate sync is performed, - // set this to false and use the `syncOne`, `syncSome`, or `syncAll` functions - // provided by `@ionic/portals-react-native`. - syncOnAdd: boolean; -}; - -type CapacitorPlugin = { - androidClassPath: string; - iosClassName: string; -}; ``` -At a minimum, when including a `portals.config.json` it must at least have the `portals` key defined with at least one valid `Portal` definition in the array. If you are using Live Updates, you must include a `LiveUpdate` configuration. If you are using Secure Live Updates, you must include the `liveUpdatesKey` in the configuration. - ### Example Configuration ```json title=portals.config.json { - "registrationKey": "YOU_PORTALS_KEY", - "portals": [ - { - "name": "user", - "startDir": "portals/shopwebapp", - "initialContext": { - "startingRoute": "/user" - }, - "plugins": [ - { - "androidClassPath": "com.capacitorjs.plugins.camera.CameraPlugin", - "iosClassName": "CAPCameraPlugin" - } - ] - }, - { - "name": "help", - "startDir": "portals/shopwebapp", - "initialContext": { - "startingRoute": "/help" - } - }, - { - "name": "checkout", - "startDir": "portals/shopwebapp", - "initialContext": { - "startingRoute": "/checkout" - } - }, - { - "name": "featuredproducts", - "startDir": "portals/featuredproducts", - "liveUpdate": { - "appId": "abcd1234", - "channel": "production", - "syncOnAdd": true - } - } - ] + "registrationKey": "YOUR_PORTALS_KEY", } ``` diff --git a/website/docs/for-react-native/how-to/using-a-capacitor-plugin.md b/website/docs/for-react-native/how-to/using-a-capacitor-plugin.md index c723125..748ad8f 100644 --- a/website/docs/for-react-native/how-to/using-a-capacitor-plugin.md +++ b/website/docs/for-react-native/how-to/using-a-capacitor-plugin.md @@ -27,8 +27,6 @@ Capacitor [Core Plugins](https://capacitorjs.com/docs/apis) are plugins built by Follow the [Android instructions](../../for-android/how-to/using-a-capacitor-plugin.md) and the [iOS instructions](../../for-ios/how-to/using-a-capacitor-plugin.md) in your native applications. When creating your portal, you will need to specify the android classpath and iOS Objective-C class name for the plugin class you intend to use: ```javascript -import { addPortal } from "@ionic/portals-react-native"; - const cameraPortal = { name: "camera", plugins: [ @@ -38,8 +36,6 @@ const cameraPortal = { } ] }; - -await addPortal(cameraPortal); ``` ### Published Plugins diff --git a/website/docs/for-react-native/how-to/using-the-portals-plugin.md b/website/docs/for-react-native/how-to/using-the-portals-plugin.md index 7e26539..e6aec0d 100644 --- a/website/docs/for-react-native/how-to/using-the-portals-plugin.md +++ b/website/docs/for-react-native/how-to/using-the-portals-plugin.md @@ -31,8 +31,6 @@ The Initial Context mechanism allows you to pass data to your web application fr You can provide initial context when registering a Portal: ```javascript -import { addPortal } from "@ionic/portals-react-native"; - const portal = { name: "maps", startDir: "web", @@ -40,8 +38,6 @@ const portal = { ic_example: "hello world", }, }; - -await addPortal(portal); ``` You can also override any initial context when rendering a Portal: @@ -51,7 +47,7 @@ import { PortalView } from "@ionic/portals-react-native"; { // Login code... @@ -69,7 +65,7 @@ const login = () => { const newTokens = /* Values from Login */ - Portals.publish(topic, newTokens); + publish(topic, newTokens); }; login(); @@ -80,7 +76,7 @@ To subscribe to the topic, call `PortalsPlugin.subcribe()` after loading the Por ```javascript import { subscribe } from "@ionic/portals-react-native"; -const subscriptionRef = await subscribe("login", (message) => { +const subscriptionRef = subscribe("login", (message) => { const auth = message.data; // Rest of the React Native app... }); diff --git a/website/docs/for-react-native/upgrade-guides.md b/website/docs/for-react-native/upgrade-guides.md index 896bb83..45aeb19 100644 --- a/website/docs/for-react-native/upgrade-guides.md +++ b/website/docs/for-react-native/upgrade-guides.md @@ -6,6 +6,130 @@ sidebar_label: Upgrade Guides import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +## Portals for React Native 0.6.0 -> 0.7.0 + +Portals for React Native version `0.7.0` is compatible with Portals Web Plugin version `0.10.x`. This release removes all of the functions that were deprecated in `0.6.0`. + +### API Changes + +#### Breaking +The stateful management of Portals has been removed in this release. The following methods have been removed: + +- `addPortal` +- `addPortals` +- `getPortal` +- `onFirstContentfulPaint` +- `onFirstInputDelay` +- `onTimeToFirstByte` +- `registerWebVitals` + +## Portals for React Native 0.5.0 → 0.6.0 + +Portals for React Native version `0.6.0` is compatible with Portals Web Plugin version `0.10.x`. + +:::caution +Portals 0.6.0 is a notable update that upgrades the Capacitor dependency to version 6. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. +::: + +First review the [Capacitor 6 Update Guide](https://capacitorjs.com/docs/updating/6-0#ios) for an overview of necessary changes. Some will not be relevant for Portals apps, but this will be a useful reference in case you encounter issues with your upgrade. + +### API Changes + +#### PortalProps.portal + +`PortalProps` has been updated to accept a `portal` prop of type `Portal` instead of a `Pick`. This change allows the display of a portal to be a declarative operation without requiring `addPortal` or `addPortals` to be called before rendering. In the case where a portal has been added via `addPortal` or `addPortals`, the behavior will be identical as in previous releases, regardless if keys other than `name` and `initialContext` are present in the portal object. + +#### Web Vitals + +`PortalProps` now includes a `webVitals` property of type `WebVitals` to enable the measurement of web vitals metrics from your portals in React Native. The `webVitals` prop is an object with the following properties: + +```typescript +{ + firstContentfulPaint?: (duration: number) => void; + firstInputDelay?: (duration: number) => void; + timeToFirstByte?: (duration: number) => void; +} +``` + +#### Deprecations + +The stateful management of Portals has been deprecated and will be removed in the next release. + +The following methods are deprecated: +- `addPortal` +- `addPortals` +- `getPortal` +- `onFirstContentfulPaint` +- `onFirstInputDelay` +- `onTimeToFirstByte` +- `registerWebVitals` + +#### Comparison of Deprecated and Replacement Methods + +##### Old + +```typescript +import { addPortal, registerWebVitals, PortalView } from '@ionic/react-portals'; +import * as React from 'react'; + +let portal = { + name: 'foo', + initialContext: { + bar: 'baz', + }, +}; + +export default function App() { + const [ready, setReady] = useState(false); + const setupPortal = async () => {} + await addPortal(portal); + await registerWebVitals( + portal.name, + (duration: number) => console.log('firstContentfulPaint', duration), + (duration: number) => console.log('firstInputDelay', duration), + (duration: number) => console.log('timeToFirstByte', duration), + ); + setReady(true); + }; + + useEffect(() => setupPortal(), []); + + return ( + { ready ? : <> } + ); +} +``` + +##### New + +```typescript +import { PortalView } from '@ionic/react-portals'; + +let portal = { + name: 'foo', + initialContext: { + bar: 'baz', + }, +}; + +export default function App() { + return { + console.log('firstContentfulPaint', duration); + }, + firstInputDelay: (duration: number) => { + console.log('firstInputDelay', duration); + }, + timeToFirstByte: (duration: number) => { + console.log('timeToFirstByte', duration); + }, + }} + />; +} +``` + ## Portals for React Native 0.4.0 → 0.5.0 Portals for React Native version 0.5.0 updates the underlying native Portals libraries to ^0.8.0. This update includes breaking changes to the API. Please read the following carefully to ensure a smooth upgrade.