Skip to content
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.

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

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

Merged
merged 39 commits into from Feb 17, 2022

Conversation

cortinico
Copy link
Contributor

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
Copy link

netlify bot commented Dec 10, 2021

✔️ 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
Copy link
Contributor

kelset commented Dec 10, 2021

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

@cortinico
Copy link
Contributor Author

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.

Comment on lines 640 to 669
#### 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
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

@gaearon gaearon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved

> 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
@ykhateeb
Copy link

Is Typescript supported in writing JavaScript spec as well?

@slorber
Copy link
Contributor

slorber commented Dec 15, 2021

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
Copy link

sorianog commented Dec 15, 2021

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.

@janicduplessis
Copy link
Contributor

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

@rachelnabors
Copy link
Contributor

  1. Breaking this into multiple pages in the Guides section is a great idea!
  2. "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 Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
docs/new-architecture-playbook.md Outdated Show resolved Hide resolved
@cortinico cortinico changed the title 📚 The New Architecture Playbook 📚 Guide: Getting Started with The New Architecture (a.k.a. the Playbook) Jan 21, 2022
@cortinico cortinico marked this pull request as ready for review February 4, 2022 18:58
@cortinico
Copy link
Contributor Author

cortinico commented Feb 4, 2022

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.

@ShikaSD ShikaSD merged commit f60b807 into main Feb 17, 2022
@yaaliuzhipeng
Copy link

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 😍

@Simek Simek deleted the feat/new-arch branch March 3, 2022 09:29
sunnylqm added a commit to reactnativecn/react-native-website that referenced this pull request Mar 26, 2022
* 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
Copy link
Contributor Author

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet