📚 Guide: Getting Started with The New Architecture (a.k.a. the Playbook) #2879

cortinico · 2021-12-10T12:32:27Z

This pull request contains the playbook for adopting the New Architecture of React Native (composed by the new NativeModule system TurboModule and the new Renderer Fabric) to your Android and iOS libraries and apps.

⚠️ Please note that this document is still a work in progress and it's constantly evolving ⚠️

At this stage, we're looking for feedbacks on the material of any form. Feel free to leave inline comments and suggestions. Users that are willing to dry-run the playbook and provided feedback are also more than welcome.

You can subscribe to this PR to receive updates whenever we release a new version of the playbook or whenever we update some of the content.

netlify · 2021-12-10T12:38:47Z

✔️ Deploy Preview for react-native ready!

🔨 Explore the source changes: ef1adcb

🔍 Inspect the deploy log: https://app.netlify.com/sites/react-native/deploys/61fd7649c84bf40007d622d4

😎 Browse the preview: https://deploy-preview-2879--react-native.netlify.app

kelset · 2021-12-10T13:35:05Z

I would suggest splitting it in multiple pages, it's way too long for a single page.

cortinico · 2021-12-10T14:46:55Z

I would suggest splitting it in multiple pages, it's way too long for a single page.

Yup we're aware of this. We're looking into splitting it into at least 3/4 different pages as it's really hard to consume as it is at the moment.

mrousavy · 2021-12-13T15:37:51Z

docs/new-architecture-playbook.md

+#### Add Folly and Other Dependencies
+
+We'll need to ensure Folly is configured properly in any projects that consume your library. With CocoaPods, we can use the `compiler_flags` and `dependency` properties to set it up.
+
+Add these to your `Pod::Spec.new` block:
+
+```ruby
+# folly_version must match the version used in React Native
+# See folly_version in react-native/React/FBReactNativeSpec/FBReactNativeSpec.podspec
+folly_version = '2021.06.28.00-v2'
+folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32'
+
+Pod::Spec.new do |s|
+  # ...
+  s.compiler_flags  = folly_compiler_flags
+
+  s.pod_target_xcconfig    = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\""
+  }
+
+  s.dependency "React"
+  s.dependency "React-RCTFabric" # This is for fabric component
+  s.dependency "React-Codegen"
+  s.dependency "RCT-Folly", folly_version
+  s.dependency "RCTRequired"
+  s.dependency "RCTTypeSafety"
+  s.dependency "ReactCommon/turbomodule/core"
+  # ...
+end
+```


I think this will break Swift Modules, since a few of those Podspecs (e.g. ReactCommon/turbomodule/core) do not expose Swift Modules / Modular Headers. This will prevent people from using Swift.

While working on VisionCamera, I've made a PR to fix this in the react-native core repo: facebook/react-native#31858 - but that was a long time ago, not sure if that still builds.

cc @sota000
I'm not really familiar with Swift support. Are you suggesting that we add "DEFINES_MODULE" => "YES" to ReactCommon/turbomodule/core and the other modules this pod depends on?

Yes I think that is the required flag for this. I think those are the three most important points for a Podspec to allow it being used in Swift modules:

Have DEFINES_MODULE set to YES

Ignore all headers by default using preserve_paths, because those might be C++ headers and importing them in Swift will break. This will also prevent nameclashes on building, see Depending on both Firebase/Firestore and SVGKit pods in the same app leads to a build error. firebase/firebase-ios-sdk#4035 for more details on that.

For those headers that are plain Objective-C headers and don't contain C++, we can add them to s.source_files. This will make them importable by other modules, including Swift.

For those headers that are Objective-C++ (or C++) and still need to be exported to be importable by other C++ (non-Swift) modules, we can either create a Subspec specifically for those, or wrap them with #ifdef __cplusplus as a last resort?

s.requires_arc = true (I think)

I think there are some improvements on Swift's C++ interoperability (see discussion here), but I'm not sure how advanced that is (those efforts started 3 years ago)

docs/new-architecture-playbook.md

gaearon

sorry for coming in unannounced — saw this and a few things jumped out at me! hope some of this will be helpful! exciting times :)

docs/new-architecture-playbook.md

gaearon · 2021-12-14T18:16:19Z

docs/new-architecture-playbook.md

+
+> To determine if your library is set up for autolinking, check the CocoaPods output after running `pod install` on an iOS project. If you see "auto linking library name", you are all set to go.
+
+### Preparing your JavaScript codebase for the new React Native Renderer (Fabric)


By the time I was in this section, I forgot we're still discussing library code. I read "your JavaScript codebase" as a cue that we're talking about the app now. Can we make this something like "Preparing your library code for ..." so that this context is not lost? It's hard to track with multiple levels of header nesting.

You're totally right on this point. We're going to move this part out of the "Library" section and just move it to its own page. This will be done in a subsequent PR.

docs/new-architecture-playbook.md

ykhateeb · 2021-12-15T00:12:19Z

Is Typescript supported in writing JavaScript spec as well?

slorber · 2021-12-15T09:25:19Z

For curious readers like me, here's a convenient link: https://deploy-preview-2879--react-native.netlify.app/docs/next/new-architecture-playbook

Edit now at: https://deploy-preview-2879--react-native.netlify.app/docs/next/new-architecture-intro

sorianog · 2021-12-15T16:17:49Z

I just started learning React Native a couple days ago. Would it be helpful if I provided my candid feedback on this PR or reserve my comments to myself?
My background: Mobile Native Engineering, Exp with Kotlin & Kotlin Multiplatform.

docs/new-architecture-playbook.md

janicduplessis · 2021-12-16T20:56:44Z

Something that would be nice to add in the guide is migrating to UIManagerHelper for dispatching events on Android.

rachelnabors · 2021-12-21T00:46:43Z

Breaking this into multiple pages in the Guides section is a great idea!
"Playbook" will be ambiguous to users searching for terms like "migration guide" or "upgrade" using the site's search bar or Google. I recommend you use these words instead for findablity.

docs/new-architecture-playbook.md

docs/new-architecture-app-modules-android.md

docs/new-architecture-app-renderer-ios.md

Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com>

cortinico · 2022-02-04T19:16:13Z

Hey all,
I wanted to give a short update on this PR.

First I wanted to thank you all on behalf of the whole team for the amazing feedbacks you all left. We're getting closer to merging this first "Getting Started" guide, which will happen sometimes next week.

If you have further feedback, feel free to leave it asap. As the number of comments on this PR grew to a point where is getting harder to follow every discussion, please consider that we might postpone some follow-ups to separate PRs.

As mentioned in this blogpost, this is going to be the first step to support the OSS community with the New Architecture rollout. We're also looking into ways to let the community be more involved into the feedback loop for the New Architecture rollout, so stay tuned if you wish to share further opinions/ideas/concerns.

yaaliuzhipeng · 2022-03-03T01:11:17Z

hey,guys . don't you think this is still hard for someone not that familiar with library development ? I think a blog to demonstrate how to create a library with turbomodule enabled from 0 to 1 is indeed needed 😍

* Generate 0.67 version of the docs (facebook#2926) * version 0.67 * Revert "version 0.67" This reverts commit f4896ac. * updated v0.67 docs cut * blogpost for 0.67 (facebook#2933) * add Lorenzo * Facebook -> Meta * 067 blogpost * add highlights and truncate * tweak * Update website/blog/2022-01-19-version-067.md * Update website/blog/2022-01-19-version-067.md Co-authored-by: Eli White <github@eli-white.com> * Move Hermes 0.10 issue callout to acknowledgements * Link the wiki Co-authored-by: Luna <lunaleaps@gmail.com> Co-authored-by: Eli White <github@eli-white.com> * blogpost: React Native - H2 2021 Recap (facebook#2937) Co-authored-by: Luna <luwe@fb.com> * Fix typo in H2 blog post: next year / half -> numbers (facebook#2938) * Use numbers for the time * Bump nanoid from 3.1.30 to 3.2.0 (facebook#2939) Bumps [nanoid](https://github.com/ai/nanoid) from 3.1.30 to 3.2.0. - [Release notes](https://github.com/ai/nanoid/releases) - [Changelog](https://github.com/ai/nanoid/blob/main/CHANGELOG.md) - [Commits](ai/nanoid@3.1.30...3.2.0) --- updated-dependencies: - dependency-name: nanoid dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * remove text in running on device (facebook#2943) * remove text on docs running-on-device (facebook#2944) * Fix small grammatical error (facebook#2942) * update copyright on website (facebook#2940) Co-authored-by: luism3861 <Eduardo_Medina@fragua.com.mx> * Fix flexShrink default value in Layout Props docs (facebook#2945) * update website font, misc UI tweaks (facebook#2947) * Fix the guide to the deprecated OpenJDK installation command. (facebook#2817) * Add function based components example for Flat list optimisation (facebook#2955) * Update typo in render-pipeline.md (facebook#2951) * Update typo in tutorial.md (facebook#2946) * Add an extra command to the troubleshooting guide for typescript template (facebook#2954) Co-authored-by: Nicola Corti <corti.nico@gmail.com> * (Image) Fix documentation for onLoad event. (facebook#2964) * - (Image) Fix documentation for onLoad event. * - (Image) Prettier. * Update image.md (facebook#2965) * Bump follow-redirects from 1.14.7 to 1.14.8 (facebook#2966) Bumps [follow-redirects](https://github.com/follow-redirects/follow-redirects) from 1.14.7 to 1.14.8. - [Release notes](https://github.com/follow-redirects/follow-redirects/releases) - [Commits](follow-redirects/follow-redirects@v1.14.7...v1.14.8) --- updated-dependencies: - dependency-name: follow-redirects dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fixed a typo in Linking page. (facebook#2968) AndroidManifext.xml should be AndroidManifest.xml * 📚 Guide: Getting Started with The New Architecture (a.k.a. the Playbook) (facebook#2879) * Initial Draft of the New Architecture Playbook * Fix c++ codeblocks not rendering correctly * Fix Android.mk containing wrong wildcards * Remove Markdown exports artifacts * Fix missing parenthesis in section header * Renamed section header as it was incomplete * Removed canCreateTurboModule as it was not used * Fix indententation and add imports to MyComponentsRegistry.java * Add missing import for MyComponentsRegistry.h * Fix the broken table * s/two/three arguments * Fix comments inside podfile * split The New Architecture guide into few pages (facebook#2882) * Fix wrong import for ./RNTMyNativeViewNativeComponent * Fix import for codegenNativeCommands * Add a banner for TypeScript support * Do not sound prescriptive with 'you will be using flow' * React concurrent mode -> React 18 * Add a banner on homepage about the number of manual steps * Fix typo on Enabling TurboModule section title Co-authored-by: Johny Urgiles <jurgiles@users.noreply.github.com> * code formatting, admonitions and small tweaks (facebook#2922) Co-authored-by: Nicola Corti <corti.nico@gmail.com> * Use descriptive component names and fix use of ref (facebook#2935) * Use descriptive component names and fix use of ref * Remove ambiguity from migrating .measure* example * Playbook => Guide * Use implicit dependency substitution for the Gradle Plugin * Specify reactRoot and codegenDir in the App setup * Add a patch for configureNdkBuild not depending on preBuild * Add the getTurboModule method * Copy the warning banner on all the pages * Update pod install to specify RCT_NEW_ARCH_ENABLED * HermesExecutorFactory header lives inside reacthermes/ and not React/ * Fix broken jsExecutorFactoryForBridge iOS * Bump used nightly version to 0.0.0-20220201-2008-79975d146 * Clarify the react-native-codegen version to use * Suggest to use :app:externalNativeBuildDebug instead of Release * Put LOCAL_SHARED_LIBRARIES on Android.mk on separate lines * Update docs/new-architecture-app-renderer-ios.md Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * Remove unnecessary duplicated `pod install` Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * Setup a New Architecture Troubleshooting page * Fix lint failures on troubleshooting section Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> Co-authored-by: Johny Urgiles <jurgiles@users.noreply.github.com> Co-authored-by: Samuel Susla <samuel.susla@gmail.com> * fix(ios): update Fabric in Podfile instructions (facebook#2973) * fix(ios): update Fabric in Podfile instructions * move fabric_enabled comment closer to the property * 📚 Add instruction for M1 users to work with Cocoapods (facebook#2974) * Update Android SDK version to 30 (facebook#2975) * Adding Explain Like I'm 5 video to the home page (facebook#2971) * Adding ELI5 video to the home page * Remove unused VideoContainer function * Combining Video and Talk sections Co-authored-by: Dmitry Vinnik <dvinnik@fb.com> * Updated expired link in docs/security (facebook#2972) * Updated link colors to meet WCAG color contrast guidelines. (facebook#2976) * Bump prismjs from 1.25.0 to 1.27.0 (facebook#2978) Bumps [prismjs](https://github.com/PrismJS/prism) from 1.25.0 to 1.27.0. - [Release notes](https://github.com/PrismJS/prism/releases) - [Changelog](https://github.com/PrismJS/prism/blob/master/CHANGELOG.md) - [Commits](PrismJS/prism@v1.25.0...v1.27.0) --- updated-dependencies: - dependency-name: prismjs dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * fix: spelling error mudule -> module (facebook#2979) * Update migration guide feedback link to the working group (facebook#2983) * Add TOC sections for the 'Render, Commit, and Mount' page (facebook#2985) * Adding Social Banner in Support of Ukraine (facebook#2986) * fix layout resizing when page includes wide code block (facebook#2980) * docs: Moving to use Announcement Banner for the Support Ukraine Initiative (facebook#2988) * Fix deeplink to react-host-components-or-host-components in Glossary (facebook#2992) * Clarify intended audience for architecture overview (facebook#2995) * changed android_hyphenation for 0.67+ (facebook#2982) * Add missing `normal` enum for Hyphenation (facebook#3002) * add ToC headers for phases on Render Pipeline page (facebook#2997) * Moving Release Wiki to react-native-website (facebook#2961) Co-authored-by: Simek <gosimek@gmail.com> * Update discrete update threading model diagram (facebook#2999) * move Fabric warning to partial, use admonition (facebook#2998) * Clarify the Configure Codegen in your Gradle File section (facebook#2993) Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * Unversion Architecture docs (facebook#3000) Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * refactor(getting-started): path to sdk binaries (facebook#2991) * bump lint stack, include `website` files in check (facebook#3004) * Add table of contents and encourage people to leave feedback in working group in Architecture Overview intro (facebook#2996) * Clarify intended audience for architecture overview * Fix broken links * Blogpost: An update on the New Architecture Rollout (facebook#3009) Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> Co-authored-by: Lorenzo Sciandra <notkelset@kelset.dev> * Use bundler to pod install (facebook#3011) * Use placeholders instead of hardcoded strings (facebook#3015) * Use @flow annotation and fix syntax (facebook#3016) * Improve documentation about JS Specs (facebook#3017) * Use more specific dependency React-Core (facebook#3020) * distinguish windows from mac keytool instructions (facebook#3019) Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * spelling fix (facebook#3021) * Rename _bridge into bridge (facebook#3013) * Use empty dicts instead of nil (facebook#3014) * 📚 Rename JSCExecutorFactory into HermesExecutorFactory (facebook#3012) * fix codegenNativeCommands section example (facebook#3024) Co-authored-by: Piotr Trocki <piotr@trocki.com> * [sync-api] Replace deprecated String.prototype.substr() (facebook#3025) * Add kotlin sample code in "Integration with an Android Fragment" documentation (facebook#2977) Co-authored-by: Andrei Shikov <andreiishikov@gmail.com> Co-authored-by: Nicola Corti <corti.nico@gmail.com> Co-authored-by: Simek <gosimek@gmail.com> * small custom CSS fixes and tweaks (facebook#3026) * Update references from Java to Java/Kotlin in the body of the article (facebook#3028) Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> * update project structure in Readme (facebook#3031) Co-authored-by: Lorenzo Sciandra <notkelset@kelset.dev> Co-authored-by: Luna <lunaleaps@gmail.com> Co-authored-by: Eli White <github@eli-white.com> Co-authored-by: Nicola Corti <ncor@fb.com> Co-authored-by: Luna <luwe@fb.com> Co-authored-by: Sota <5866096+sota000@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Luis Medina Huerta <luism3861@gmail.com> Co-authored-by: Palash Shrivastava <35087196+BattleOfPlassey@users.noreply.github.com> Co-authored-by: Michael Evans <michaelrevans@live.co.uk> Co-authored-by: luism3861 <Eduardo_Medina@fragua.com.mx> Co-authored-by: jzxchiang1 <15524484+jzxchiang1@users.noreply.github.com> Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com> Co-authored-by: 1natsu <1natsu172@users.noreply.github.com> Co-authored-by: DIBYAJYOTI MISHRA <dibyajyotimishra14@gmail.com> Co-authored-by: Jiovanna Manriquez <jiovannamanriquez@gmail.com> Co-authored-by: markbell2410 <24226636+markbell2410@users.noreply.github.com> Co-authored-by: Nicola Corti <corti.nico@gmail.com> Co-authored-by: Erick Maeda Lopes <erick.maeda26@gmail.com> Co-authored-by: Kavanaugh Latiolais <kav@pelo.tech> Co-authored-by: hj <jiehecd@gmail.com> Co-authored-by: Johny Urgiles <jurgiles@users.noreply.github.com> Co-authored-by: Samuel Susla <samuel.susla@gmail.com> Co-authored-by: Tommy Nguyen <4123478+tido64@users.noreply.github.com> Co-authored-by: Riccardo <riccardo.cipolleschi@gmail.com> Co-authored-by: Kid <44045911+kidonng@users.noreply.github.com> Co-authored-by: Dmitry Vinnik <dmitryvinn@users.noreply.github.com> Co-authored-by: Dmitry Vinnik <dvinnik@fb.com> Co-authored-by: Vishwa Gaurav <81325730+VishwaGauravIn@users.noreply.github.com> Co-authored-by: blavalla <blavalla@gmail.com> Co-authored-by: RayKay91 <61206305+RayKay91@users.noreply.github.com> Co-authored-by: zegermouw <zegermouw@gmail.com> Co-authored-by: Nicolas <nicolashortaadam@gmail.com> Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com> Co-authored-by: Henry Hobhouse <henryhobhouse@gmail.com> Co-authored-by: Samuel Susla <samuelsusla@fb.com> Co-authored-by: Danilo Bürger <info@danilobuerger.de> Co-authored-by: Riccardo <cipolleschi@fb.com> Co-authored-by: Fernando Cervera <86963649+fernandocervera-abi@users.noreply.github.com> Co-authored-by: Rajesh Sharma <broncha@rajesharma.com> Co-authored-by: troZee <12766071+troZee@users.noreply.github.com> Co-authored-by: Piotr Trocki <piotr@trocki.com> Co-authored-by: CommanderRoot <CommanderRoot@users.noreply.github.com> Co-authored-by: David Vacca <515103+mdvacca@users.noreply.github.com> Co-authored-by: Andrei Shikov <andreiishikov@gmail.com>

cortinico · 2022-04-14T09:23:46Z

Is Typescript supported in writing JavaScript spec as well?

Following up here as it was a long requested feature. As of today, you can use TypeScript to write your specs for the New Architecture. We've update the docs and opened a thread to discuss it in the working group:

facebook-github-bot added CLA Signed p: Facebook Partner labels Dec 10, 2021

mrousavy reviewed Dec 13, 2021

View reviewed changes

raedle reviewed Dec 13, 2021

View reviewed changes