Migrate from react-native-windows-init to react-native init-windows for new RNW projects

[jonthysell]

This item tracks all the work necessary to build a new simpler path for creating new RNW projects, with a primary focus of enabling the React Native New Architecture and golden-path supported scenarios.

Tasks

Create named "old architecture" templates from existing UWP templates (in /vnext)

Preview Give feedback

1. Create a "uwp-cpp-app" template, defaulting to: C++, Paper, Chakra, Source-based, UWP app #12147
   Area: CLI enhancement +2
   
2. Create a "uwp-cs-app" template, defaulting to: C#, Paper, Chakra, Source-based, UWP app #12148
   Area: CLI enhancement +2
   
3. Create a "uwp-cpp-lib" template, defaulting to: C++, Paper, Chakra, Source-based, UWP lib #12149
   Area: CLI enhancement +2
4. Create a "uwp-cs-lib" template, defaulting to: C#, Paper, Chakra, Source-based, UWP lib #12150
   Area: CLI enhancement +2
   

Create named "new architecture" templates (in /vnext)

Preview Give feedback

1. Enable creation of a new Fabric app from template via the CLI #11908
   Area: App Template Area: CLI Area: Fabric New Architecture enhancement +5
   
2. Create a "new-app" template, defaulting to: C++, Fabric, Hermes, NuGet-based, Win32 app #12171
   Area: Fabric New Architecture enhancement +3
   
3. Create a "new-lib" template, defaulting to C++, Fabric, Hermes, NuGet-based, Win32 lib #12480
   Area: Fabric Area: Native Modules New Architecture +3
   

Create RNW CLI init-windows command (in /packages/@react-native-windows/cli)

Preview Give feedback

1. Create a new initWindowsInternal() method that copies and fills in files from the given template name #12151
   Area: CLI enhancement +2
   
2. Create a new CLI init command which calls initWindowsInternal (wrapped in the appropriate telemetry) #12152
   Area: CLI enhancement +2
   
3. Add functionality for init-windows to list available templates (with descriptions?) #13459
   Area: App Template Area: CLI Area: Library Template Workstream: New Arch Soft Launch enhancement +5
   
4. Expose initWindowsInternal() such that other scripts could call it directly #13460
   +0

Stop using react-native-windows-init

Preview Give feedback

1. Put checks in react-native-windows-init to prevent trying to target newer RN / RNW versions and give useful error messages to the user #13461
   Area: CLI +1
   
2. Delete the jobs/cli-init.yml jobs still calling react-native-windows-init #13462
   Area: Build Infrastructure +1
   

Documentation / Samples

Preview Give feedback

1. Update documentation with steps for creating a new project using react-native init-windows #13394
   +0
2. Update samples upgrade steps / CI to use the new react-native init-windows #13464
   Area: Samples Documentation +2
   
3. Remove references to deprecated CLI arguments (refer to using ExperimentalFeatures.props where appropriate)
4. Add upgrade documentation for users attempting to transition old apps to the new templates using react-native init-windows #13463
   Documentation New Architecture Scenario: Upgrade +3
   

Deprecate and remove old code

Preview Give feedback

1. Deprecate the WindowsAppSDK app template and projects #11744
   Area: Infrastructure Platform: WinAppSDK enhancement +3
   
2. After RNW Paper is no longer supported, delete the old template code from RNW #13465
   Area: App Template Area: Fabric Area: Paper New Architecture Old Architecture Workstream: Releases and Integrations enhancement +7
3. After RNW Paper is no longer supported, deprecate the react-native-windows-init package all together #13466
   Area: App Template Area: CLI Area: Fabric Area: Paper New Architecture Old Architecture Workstream: Releases and Integrations enhancement +8

[jonthysell]

Background context:

RNW Init v1

RNW Init v1: Basics

• Customers start with a React Native app, typically having been created by the npx react-native init command
  • This includes the JS app code and native app hosts for iOS / Android
• To add Windows support via RNW, customers use the npx react-native-windows-init command
  • This adds our RNW dependencies and a native app host for Windows
• This new project functionality is primarily accomplished by these three RNW packages:
  1. react-native-windows-init
  2. react-native-windows
  3. @react-native-windows/cli

RNW Init v1: Package Versioning

RNW Init v1: CLI Arguments

Argument	Type	Default	Req.	Hidden	Description
--help	bool	False	N	N	Show Help
--version	string	Auto¹	Y¹	N	Specify RNW version
--namespace	string	Auto²	Y²	N	Specify namespace for native code
--language	string	"cpp"	Y	N	Specify programming language C++ or C#
--projectType	string	"app"	N	N	Specify app or library (0.64+)
--useWinUI3	bool	False	N	Y	Target WinUI 3.0 instead of UWP XAML
--useHermes	bool	False	N	Y	Use Hermes instead of Chakra (0.64+)
--experimentalNuGetDependency	bool	False	N	Y	Build against Microsoft.ReactNative NuGet instead of source
--verbose	bool	False	N	N	Verbose output
--overwrite	bool	False	N	N	Overwrite files without prompting
--telemetry	bool	False	N	N	Send usage telemetry to MSFT
--useDevMode	bool	False	N	Y	Use local RNW clone
--nuGetTestFeed	string	""	N	Y	Use specified NuGet test feed
--nuGetTestVersion	string	""	N	Y	Use specified NuGet test version

¹: If unspecified, calculated based on existing project RN version
²: If unspecified, calculated based on existing project name

RNW Init v1: Code Flow

[jonthysell]

More background context:

The Problems

1. The latest RNW Init must support all past versions of RNW
   1. The ABI between the packages is static
2. There are too many CLI arguments
   1. Produces a rather large matrix of combinations (not all supported)
   2. Not every argument is supported by every RNW version
   3. Experimental Features as args means we can’t deprecate args
3. Important changes to experimental features in the near/medium term
   1. Removing the WinUI3 template project
   2. Switch to Hermes as the default engine
   3. Switch to Fabric as the default architecture
   4. Switch to consuming NuGet instead of source
4. No way to invoke project init without RNW Init

[chrisglein]

@jonthysell FYI adding link to #13362. Resolve when appropriate.

[jonthysell]

I'm opening the remaining valid issues to be tracked toward milestones indivudually and moving this into next until it's all done

[Saadnajmi]

Curious why the change. Should macOS follow suit?

[jonthysell]

Curious why the change. Should macOS follow suit?

Because the react-native-windows-init package needed to be evergreen for all RNW versions, we could never drastically change or remove args that older versions still supported (like --useHermes, which is the default for RNW >= 0.74, but not earlier, our prototpye winappsdk work which is now abandoned, etc.) so the command arg matrix was becoming this big mess of which version ranges support which args, etc.

So we built a RNW CLI command react-native init-windows to handle all the work for creating new projects (now with a cleaner API surface based on named templates). So once you add RNW to your project like any other dep, then the init-command is directly available and already directly tied to whichever RNW version you chose.

With that working, the old, evergreen react-native-windows-init command really only serves one purpose - to try to "guess" which version of RNW applies to your project and yarn add it to the package.json for you. It's easier to get rid of that than try to massage it even more to support the totally new API surface of our new commands.

But it's okay, now we can just tell devs "yarn add the RNW version you want" then you can use "react-native init-windows" at any time to restamp a windows template in your project folder. It's faster and more flexible.

As for what macos should do - do you need to support more than one type of template and/or you have a lot of args you allow to be passed into react-native-macos-init?

[jonthysell]

Closing this as the individual items track the remaining work.