You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guides/api-development-strategy.md
+16-91Lines changed: 16 additions & 91 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,115 +5,40 @@ new: true
5
5
6
6
# API Development Strategy
7
7
8
-
Let's cut to the chase - major version upgrades can be a _pain_. Especially for something as foundational to your application as the framework or router it's built on. For Remix and React Router, we want to do our best to give you the smoothest upgrade experience possible.
8
+
React Router is foundational to your application. We want to make sure that upgrading to new major versions is as smooth as possible while still allowing us to adjust and enhance the behavior and API as the React ecosystem advances.
9
9
10
-
<docs-info>This strategy is discussed in more detail in our [Future Flags][future-flags-blog-post] blog post, so give that a read if you want any more info at the end of this doc!</docs-info>
10
+
Our strategy and motivations are discussed in more detail in our [Future Flags][future-flags-blog-post] blog post.
11
11
12
-
## Goals
12
+
## Future Flags
13
13
14
-
Our goals for major Remix and React Router releases are:
14
+
When an API changes in a breaking way, it is introduced in a future flag. This allows you to opt-in to one change a time before it becomes the default in the next major version.
15
15
16
-
-Developers can opt-into SemVer-major features individually _as they are released_ instead of having to wait to adopt them all at once when a new major version hits NPM
17
-
-Having opted into features ahead-of-time, developers can upgrade to new major versions in a single short-lived branch/commit (hours, not weeks)
16
+
-Without enabling the future flag, nothing changes about your app
17
+
-Enabling the flag changes the behavior for that feature
18
18
19
-
## Implementation
19
+
All current future flags are documented in the [Future Flags Guide](../upgrading/future) to help you stay up-to-date.
20
20
21
-
We plan to do this via what we're calling **Future Flags** that you'll provide when you initialize your [Data Router][picking-a-router]. Think of these as **feature flags for future features**. As we implement new features, we always try to do them in a backwards-compatible way. But when a breaking change is warranted, we don't table that feature up for an _eventual_ v7 release. Instead, we add a **Future Flag** and implement the new feature alongside the current behavior in a v6 minor release. This allows users to start using the feature, providing feedback, and reporting bugs _immediately_.
21
+
## Unstable Flags
22
22
23
-
That way, not only can you adopt features incrementally (and eagerly without a major version bump), we can also work out any kinks incrementally _before_ releasing v7. Eventually we also then add deprecation warnings to the v6 releases to nudge users to the new behavior. Then in v7 we remove the old v6 approach, remove the deprecations, and remove the flag - thus making the flagged behavior the new default in v7. If at the time v6 is released, an application has opted into _all_ future flags and updated their code - then they should just be able to update their dependency to v7, delete the future flags, and be running on v7 in a matter of minutes.
23
+
Unstable flags are for features still being designed and developed and made available to our users to help us get it right.
24
24
25
-
## Unstable vs. V7 Flags
25
+
Unstable flags are not recommended for production:
26
26
27
-
Future flags come in 2 forms:
27
+
- they will change without warning and without upgrade paths
28
+
- they will have bugs
29
+
- they aren't documented
30
+
- they may be scrapped completely
28
31
29
-
**`future.unstable_feature`**
32
+
When you opt-in to an unstable flag you are becoming a contributor to the project, rather than a user. We appreciate your help, but please be aware of the new role!
30
33
31
-
`unstable_` flags allow us to iterate on the API with early adopters as if we're in `v0.x.x` versions, but for a specific feature. This avoids churning the API for all users and arriving at better APIs in the final release. This _does not mean_ that we think the feature is bug-ridden! We _absolutely_ want early adopters to start using these features so we can iterate on (and/or gain confidence in) the API.
32
-
33
-
**`future.v7_feature`**
34
-
35
-
`v7_` indicates a breaking change from v6 behavior and implies (1) that the API is considered stable and will not under any more breaking changes and (2) that the API will become the default behavior in v7. A `v7_` flag _does not_ mean the feature is bug-free - no software is! Our recommendation is to upgrade to v7 flags as you have the time, as it will make your v7 upgrade _much_ smoother.
34
+
To learn about current unstable flags, keep an eye on the [CHANGELOG](../start/changelog).
36
35
37
36
### Example New Feature Flow
38
37
39
38
The decision flow for a new feature looks something like this (note this diagram is in relation to Remix v1/v2 but applies to React Router v6/v7 as well):
40
39
41
40
![Flowchart of the decision process for how to introduce a new feature][feature-flowchart]
42
41
43
-
The lifecycle is thus either:
44
-
45
-
- Non-Breaking + Stable API Feature -> Lands in v6
46
-
- Non-Breaking + Unstable API -> `future.unstable_` flag -> Lands in v6
47
-
- Breaking + Stable API Feature -> `future.v7_` flag -> Lands in v7
48
-
- Breaking + Unstable API -> `future.unstable_` flag -> `future.v7_` flag -> Lands in v7
49
-
50
-
## Current Future Flags
51
-
52
-
Here's the current future flags in React Router v6 today.
53
-
54
-
### `@remix-run/router` Future Flags
55
-
56
-
These flags are only applicable when using a [Data Router][picking-a-router] and are passed when creating the `router` instance:
The following future flags are stable and ready to adopt. To read more about future flags see [Development Strategy](../guides/api-development-strategy)
10
+
11
+
## Update to latest v6.x
12
+
13
+
First update to the latest minor version of v6.x to have the latest future flags.
14
+
15
+
👉 **Update to latest v6**
16
+
17
+
```shellscript nonumber
18
+
npm install react-router-dom@6
19
+
```
20
+
21
+
## v7_relativeSplatPath
22
+
23
+
**Background**
24
+
25
+
Changes the relative path matching and linking for multi-segment splats paths like `dashboard/*` (vs. just `*`). [View the CHANGELOG](https://github.com/remix-run/react-router/blob/main/packages/react-router-dom/CHANGELOG.md#minor-changes-2) for more information.
26
+
27
+
👉 **Enable the flag**
28
+
29
+
Enabling the flag depends on the type of router:
30
+
31
+
```tsx
32
+
<BrowserRouter
33
+
future={{
34
+
v7_relativeSplatPath: true,
35
+
}}
36
+
/>
37
+
```
38
+
39
+
```tsx
40
+
createBrowserRouter(routes, {
41
+
future: {
42
+
v7_relativeSplatPath: true,
43
+
},
44
+
});
45
+
```
46
+
47
+
**Update your Code**
48
+
49
+
If you have any routes with a path + a splat like `<Route path="dashboard/*">` and has relative links like `<Link to="relative">` or `<Link to="../relative">` beneath it, you will need to update your code.
50
+
51
+
👉 **Split the `<Route>` into two**
52
+
53
+
Split any multi-segment splat `<Route>` into a parent route with the path and a child route with the splat:
Update any `<Link>` elements within that route tree to include the extra `..` relative segment to continue linking to the same place:
79
+
80
+
```diff
81
+
function Dashboard() {
82
+
return (
83
+
<div>
84
+
<h2>Dashboard</h2>
85
+
<nav>
86
+
- <Link to="/">Dashboard Home</Link>
87
+
- <Link to="team">Team</Link>
88
+
- <Link to="projects">Projects</Link>
89
+
+ <Link to="../">Dashboard Home</Link>
90
+
+ <Link to="../team">Team</Link>
91
+
+ <Link to="../projects">Projects</Link>
92
+
</nav>
93
+
94
+
<Routes>
95
+
<Route path="/" element={<DashboardHome />} />
96
+
<Route path="team" element={<DashboardTeam />} />
97
+
<Route
98
+
path="projects"
99
+
element={<DashboardProjects />}
100
+
/>
101
+
</Routes>
102
+
</div>
103
+
);
104
+
}
105
+
```
106
+
107
+
## v7_startTransition
108
+
109
+
**Background**
110
+
111
+
This uses `React.useTransition` instead of `React.useState` for Router state updates. View the [CHANGELOG](https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v7_starttransition) for more information.
112
+
113
+
👉 **Enable the flag**
114
+
115
+
```tsx
116
+
<BrowserRouter
117
+
future={{
118
+
v7_startTransition: true,
119
+
}}
120
+
/>
121
+
122
+
// or
123
+
<RouterProvider
124
+
future={{
125
+
v7_startTransition: true,
126
+
}}
127
+
/>
128
+
```
129
+
130
+
👉 **Update your Code**
131
+
132
+
You don't need to update anything unless you are using `React.lazy`_inside_ of a component.
133
+
134
+
Using `React.lazy` inside of a component is incompatible with `React.useTransition` (or other code that makes promises inside of components). Move `React.lazy` to the module scope and stop making promises inside of components. This is not a limitation of React Router but rather incorrect usage of React.
135
+
136
+
## v7_fetcherPersist
137
+
138
+
<docs-warning>If you are not using a `createBrowserRouter` you can skip this</docs-warning>
139
+
140
+
**Background**
141
+
142
+
The fetcher lifecycle is now based on when it returns to an idle state rather than when its owner component unmounts: [View the CHANGELOG](https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#persistence-future-flag-futurev7_fetcherpersist) for more information.
143
+
144
+
**Enable the Flag**
145
+
146
+
```tsx
147
+
createBrowserRouter(routes, {
148
+
future: {
149
+
v7_fetcherPersist: true,
150
+
},
151
+
});
152
+
```
153
+
154
+
**Update your Code**
155
+
156
+
It's unlikely to affect your app. You may want to check any usage of `useFetchers` as they may persist longer than they did before. Depending on what you're doing, you may render something longer than before.
157
+
158
+
## v7_normalizeFormMethod
159
+
160
+
<docs-warning>If you are not using a `createBrowserRouter` you can skip this</docs-warning>
161
+
162
+
This normalizes `formMethod` fields as uppercase HTTP methods to align with the `fetch()` behavior. [View the CHANGELOG](https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#futurev7_normalizeformmethod) for more information.
163
+
164
+
👉 **Enable the Flag**
165
+
166
+
```tsx
167
+
createBrowserRouter(routes, {
168
+
future: {
169
+
v7_normalizeFormMethod: true,
170
+
},
171
+
});
172
+
```
173
+
174
+
**Update your Code**
175
+
176
+
If any of your code is checking for lowercase HTTP methods, you will need to update it to check for uppercase HTTP methods (or call `toLowerCase()` on it).
177
+
178
+
👉 **Compare `formMethod` to UPPERCASE**
179
+
180
+
```diff
181
+
-useNavigation().formMethod === "post"
182
+
-useFetcher().formMethod === "get";
183
+
+useNavigation().formMethod === "POST"
184
+
+useFetcher().formMethod === "GET";
185
+
```
186
+
187
+
## v7_partialHydration
188
+
189
+
<docs-warning>If you are not using a `createBrowserRouter` you can skip this</docs-warning>
190
+
191
+
This allows SSR frameworks to provide only partial hydration data. It's unlikely you need to worry about this, just turn the flag on. [View the CHANGELOG](https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#partial-hydration) for more information.
0 commit comments