microsoft / react-native-windows

A framework for building native Windows apps with React.
https://microsoft.github.io/react-native-windows/
Other
16.1k stars 1.13k forks source link

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

Open jonthysell opened 11 months ago

jonthysell commented 11 months ago

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`)
- [ ] https://github.com/microsoft/react-native-windows/issues/12147
- [ ] https://github.com/microsoft/react-native-windows/issues/12148
- [ ] https://github.com/microsoft/react-native-windows/issues/12149
- [ ] https://github.com/microsoft/react-native-windows/issues/12150
#### Create named "new architecture" templates (in `/vnext`)
- [ ] #11908
- [ ] https://github.com/microsoft/react-native-windows/issues/12171
- [ ] https://github.com/microsoft/react-native-windows/issues/12480
#### Create RNW CLI `init-windows` command  (in `/packages/@react-native-windows/cli`)
- [ ] https://github.com/microsoft/react-native-windows/issues/12151
- [ ] https://github.com/microsoft/react-native-windows/issues/12152
- [ ] Add functionality for `init-windows` to list available templates (with descriptions?)
- [ ] Add functionality for `init-windows` to specify callbacks to be called with a given template, and some common utilities (like modifying package.json or jest/metro configuration files, rather than stamping over them)
- [ ] Expose `initWindowsInternal()` such that other scripts could call it directly
#### Stop using `react-native-windows-init`
- [ ] Put checks in `react-native-windows-init` to prevent trying to target newer RN / RNW versions and give useful error messages to the user
- [ ] Delete the `jobs/cli-init.yml` jobs still calling `react-native-windows-init`
#### Documentation / Samples
- [ ] https://github.com/microsoft/react-native-windows/issues/13394
- [ ] Update samples upgrade steps / CI to use the new `react-native init-windows`
- [ ] Remove references to deprecated CLI arguments (refer to using `ExperimentalFeatures.props` where appropriate)
- [ ] Add upgrade documentation for users attempting to transition old apps to the new templates using `react-native init-windows`
#### Deprecate and remove old code
- [ ] #11744
- [ ] After RNW Paper is no longer supported, delete the old template code from RNW
- [ ] After RNW Paper is no longer supported, delete the `react-native-windows-init` package all together
jonthysell commented 11 months ago

Background context:

RNW Init v1

RNW Init v1: Basics

RNW Init v1: Package Versioning

image

RNW Init v1: CLI Arguments

Argument Type Default Req. Hidden Description
--help bool False N N Show Help
--version string Auto¹ N Specify RNW version
--namespace string Auto² 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

image

jonthysell commented 11 months ago

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 commented 1 week ago

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