booooooooosh

remix-run · Mar 28, 2023 · 8733ef8 · 8733ef8
1 parent 1f53ad1
commit 8733ef8
Show file tree

Hide file tree

Showing 16 changed files with 526 additions and 391 deletions.
diff --git a/docs/file-conventions/remix-config.md b/docs/file-conventions/remix-config.md
@@ -135,18 +135,6 @@ The `serverBuildTarget` can be one of the following:
 - [`"node-cjs"`][node-cjs]
 - [`"vercel"`][vercel]
 
-**Migration Table:**
-
-| serverBuildTarget    | publicPath         | serverBuildPath                         | serverConditions | serverMainFields        | serverModuleFormat | serverPlatform | serverDependenciesToBundle | serverMinify |
-| -------------------- | ------------------ | --------------------------------------- | ---------------- | ----------------------- | ------------------ | -------------- | -------------------------- | ------------ |
-| `arc`                | `/\_static/build/` | `server/index.js`                       |                  | `main, module`          | `cjs`              | `node`         |                            | `false`      |
-| `cloudflare-pages`   | `/build/`          | `functions/[[path]].js`                 | `worker`         | `browser, module, main` | `esm`              | `neutral`      | `all`                      | `true`       |
-| `cloudflare-workers` | `/build/`          | `build/index.js`                        | `worker`         | `browser, module, main` | `esm`              | `neutral`      | `all`                      | `true`       |
-| `deno`               | `/build/`          | `build/index.js`                        | `deno, worker`   | `module, main`          | `esm`              | `neutral`      | `all`                      | `false`      |
-| `netlify`            | `/build/`          | `.netlify/functions-internal/server.js` |                  | `main, module`          | `cjs`              | `node`         |                            | `false`      |
-| `node-cjs`           | `/build/`          | `build/index.js`                        |                  | `main, module`          | `cjs`              | `node`         |                            | `false`      |
-| `vercel`             | `/build/`          | `api/index.js`                          |                  | `main, module`          | `cjs`              | `node`         |                            | `false`      |
-
 ## serverConditions
 
 The order of conditions to use when resolving server dependencies' `exports`

diff --git a/docs/file-conventions/route-files-v2.md b/docs/file-conventions/route-files-v2.md
@@ -1,10 +1,11 @@
 ---
 title: Route File Naming (v2)
+new: true
 ---
 
 # Route File Naming (v2)
 
-You can opt-in to the new route file naming convention with a future flag in Remix config. It will be the default behavior in the future when v2 ships. For background on this change, [see the RFC][flatroutes-rfc].
+You can opt-in to the new route file naming convention with a future flag in Remix config.
 
 ```js filename=remix.config.js
 module.exports = {
@@ -14,10 +15,6 @@ module.exports = {
 };
 ```
 
-We encourage you to make this change early so upgrading is easy. We'll be providing a helper function to use the old convention in v2 if you prefer it.
-
----
-
 While you can configure routes in [remix.config.js][remix-config], most routes are created with this file system convention. Add a file, get a route.
 
 Please note that you can use either `.jsx` or `.tsx` file extensions. We'll stick with `.tsx` in the examples to avoid duplication.

diff --git a/docs/file-conventions/routes-files.md b/docs/file-conventions/routes-files.md
@@ -4,6 +4,8 @@ title: Route File Naming
 
 # Route File Naming
 
+<docs-warning>The route file convention is changing in v2. You can prepare for this change at your convenience with the `v2_routeConvention` future flag. For instructions on making this change see the [v2 guide][v2guide].</docs-warning>
+
 Setting up routes in Remix is as simple as creating files in your `app` directory. These are the conventions you should know to understand how routing in Remix works.
 
 Please note that you can use either `.js`, `.jsx` or `.tsx` file extensions depending on whether or not you use TypeScript. We'll stick with `.tsx` in the examples to avoid duplication.
@@ -299,10 +301,6 @@ Because some characters have special meaning, you must use our escaping syntax i
   Note, you could even do `app/routes/sitemap[.]xml.tsx` if you wanted to only wrap the part that needs to be escaped. It makes no difference. Choose the one you like best.
 </docs-info>
 
-## v2 Route Convention
-
-The Route file naming convention is changing in v2 to make file organization simpler and make co-location of modules used by your routes simpler. You can opt-in to the new convention today, [see the Route Convention v2 page][routeconvention-v2] but you don't need to today, or ever if you don't want to.
-
 [loader]: ../route/loader
 [action]: ../route/action
 [meta]: ../route/meta
@@ -317,5 +315,4 @@ The Route file naming convention is changing in v2 to make file organization sim
 [routing-guide]: ../guides/routing
 [root-route]: #root-route
 [resource-route]: ../guides/resource-routes
-[routeconvention-v2]: ./route-files-v2
-[flatroutes-rfc]: https://github.com/remix-run/remix/discussions/4482
+[v2guide]: ../pages/v2#file-system-route-convention
diff --git a/docs/guides/styling.md b/docs/guides/styling.md
@@ -1,5 +1,6 @@
 ---
 title: Styling
+new: true
 ---
 
 # Styling

diff --git a/docs/hooks/use-fetcher.md b/docs/hooks/use-fetcher.md
@@ -72,7 +72,7 @@ You can know the state of the fetcher with `fetcher.state`. It will be one of:
 
 ## `fetcher.type`
 
-<docs-warning>`fetcher.type` is deprecated and will be removed in v2. [See the v2 guide][v2]</docs-warning>
+<docs-warning>`fetcher.type` will be removed in v2. For instructions on preparing for this change see the [v2 guide][v2guide].</docs-warning>
 
 This is the type of state the fetcher is in. It's like `fetcher.state`, but more granular. Depending on the fetcher's state, the types can be the following:
 
@@ -94,7 +94,7 @@ This is the type of state the fetcher is in. It's like `fetcher.state`, but more
 
 ## `fetcher.submission`
 
-<docs-warning>`fetcher.submission` is deprecated and will be removed in v2. Instead, the fields inside of `submission` have been flattened onto the `fetcher` itself (`fetcher.formMethod`, `fetcher.formAction`, `fetcher.formData`, `fetcher.formEncType`)</docs-warning>
+<docs-warning>`fetcher.submission` will be flattened into the fetcher object itself in v2. For instructions on preparing for this change see the [v2 guide][v2guide].</docs-warning>
 
 When using `<fetcher.Form>` or `fetcher.submit()`, the form submission is available to build optimistic UI.
 
@@ -438,4 +438,4 @@ function CitySearchCombobox() {
 [usetransition]: ./use-transition
 [useactiondata]: ./use-action-data
 [useloaderdata]: ./use-loader-data
-[v2]: ../pages/v2#usefetcher
+[v2guide]: ../pages/v2#usefetcher
diff --git a/docs/hooks/use-transition.md b/docs/hooks/use-transition.md
@@ -4,9 +4,7 @@ title: useTransition
 
 # `useTransition`
 
-<docs-error>This API will be removed in v2 in favor of [`useNavigation`][use-navigation]. You can start using the new `useNavigation` hook today to make upgrading in the future easy, but you can keep using `useTransition` until v2.</docs-error>
-
----
+<docs-warning>`useTransition` will be removed in v2 in favor of [`useNavigation`][use-navigation]. You can prepare for this change at your convenience by updating to [`useNavigation`][use-navigation]. For instructions on making this change see the [v2 guide][v2guide]</docs-warning>
 
 <docs-success>Watch the <a href="https://www.youtube.com/playlist?list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6">📼 Remix Singles</a>: <a href="https://www.youtube.com/watch?v=y4VLIFjFq8k&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6">Pending UI</a>, <a href="https://www.youtube.com/watch?v=bMLej7bg5Zo&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6">Clearing Inputs After Form Submissions</a>, and <a href="https://www.youtube.com/watch?v=EdB_nj01C80&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6">Optimistic UI</a></docs-success>
 
@@ -118,63 +116,10 @@ function SubmitButton() {
 }
 ```
 
-### Moving away from `transition.type`
-
-The `type` field has been removed in the new `useNavigation` hook (which will replace `useTransition` in Remix v2). We've found that `state` is sufficient for almost all use-cases, and when it's not you can derive sub-types via `navigation.state` and other fields. Also note that the `loaderSubmission` type is now represented with `state: "loading"`. Here's a few examples:
-
-```js
-function Component() {
-  let navigation = useNavigation();
-
-  let isActionSubmission =
-    navigation.state === "submitting";
-
-  let isActionReload =
-    navigation.state === "loading" &&
-    navigation.formMethod != null &&
-    navigation.formMethod != "get" &&
-    // We had a submission navigation and are loading the submitted location
-    navigation.formAction === navigation.pathname;
-
-  let isActionRedirect =
-    navigation.state === "loading" &&
-    navigation.formMethod != null &&
-    navigation.formMethod != "get" &&
-    // We had a submission navigation and are now navigating to different location
-    navigation.formAction !== navigation.pathname;
-
-  let isLoaderSubmission =
-    navigation.state === "loading" &&
-    navigation.state.formMethod === "get" &&
-    // We had a loader submission and are navigating to the submitted location
-    navigation.formAction === navigation.pathname;
-
-  let isLoaderSubmissionRedirect =
-    navigation.state === "loading" &&
-    navigation.state.formMethod === "get" &&
-    // We had a loader submission and are navigating to a new location
-    navigation.formAction !== navigation.pathname;
-}
-```
-
 ## `transition.submission`
 
 Any transition that started from a `<Form>` or `useSubmit` will have your form's submission attached to it. This is primarily useful to build "Optimistic UI" with the `submission.formData` [`FormData`][form-data] object.
 
-### Moving away from `transition.submission`
-
-The `submission` field has been removed in the new `useNavigation` hook (which will replace `useTransition` in Remix v2) and the same sub-fields are now exposed directly on the `navigation`:
-
-```js
-function Component() {
-  let navigation = useNavigation();
-  // navigation.formMethod
-  // navigation.formAction
-  // navigation.formData
-  // navigation.formEncType
-}
-```
-
 ## `transition.location`
 
 This tells you what the next location is going to be. It's most useful when matching against the next URL for custom links and hooks.
@@ -207,3 +152,4 @@ Note that this link will not appear "pending" if a form is being submitted to th
 [usefetcher]: ./use-fetcher
 [form-data]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
 [use-navigation]: ./use-navigation
+[v2guide]: ../pages/v2#usetransition
diff --git a/docs/index.md b/docs/index.md
@@ -8,37 +8,35 @@ hidden: true
 
 # Remix Docs
 
-## Getting Started
-
 ```sh
 npx create-remix@latest
 ```
 
-We **strongly encourage you** to do one of the tutorials before anything else. Remix is different. The tutorials will show you how to start with web fundamentals and then progressively enhance your app to the modern UX you're after.
+## Getting Started
 
 <docs-cards>
-  <a href="v1/tutorials/blog" aria-label="Developer Blog Tutorial">
+  <a href="pages/technical-explanation" aria-label="Technical Explanation">
     <docs-card>
-      <h4>Quickstart</h4>
-      <p>Spend your first few minutes with Remix here and let us introduce some of the core features as quickly as possible. After this you can go explore the docs or dive deeper with the other tutorials. We'll build a little markdown blog with data loading, actions, form validation, redirects, and more.</p>
+      <h4>Technical Explanation</h4>
+      <p>If you're wondering what Remix is, this is the page for you. Learn how Remix is four primary things: a compiler, an HTTP handler, a server framework, and a browser framework.</p>
     </docs-card>
   </a>
-  <a href="v1/tutorials/jokes" aria-label="Jokes App Tutorial">
+  <a href="pages/v2" aria-label="Preparing for v2">
     <docs-card>
-      <h4>Jokes App Deep Dive</h4> 
-      <p>Dive deep into Remix and full stack development with this app. It's backed by a SQL database, user authentication and session, and of course some modern UI finishes. You'll learn about nested routes, sessions, data loading, data mutations, progressive enhancement, and more. Get a feel for what a data-backed web app feels like with Remix.</p>
+      <h4>Preparing for v2</h4> 
+      <p>Remix v2 is coming soon! All of the new APIs and behaviors are available already in v1 behind Future Flags. This doc will help you incrementally adopt each one so that when its time to update to v2, you don't have to change a thing.</p>
     </docs-card>
   </a>
-  <a href="v1/api/conventions" aria-label="Conventional APIs">
+  <a href="tutorials/blog" aria-label="Developer Blog Tutorial">
     <docs-card>
-      <h4>Conventional APIs</h4> 
-      <p>Remix has a handful of conventions to make web application development a breeze. You'll spend some time in this document when you're first learning Remix, but probably won't need it much after you get your feet wet.</p>
+      <h4>Blog Tutorial</h4>
+      <p>Spend your first few minutes with Remix here and let us introduce some of the core features as quickly as possible. After this you can go explore the docs or dive deeper with the other tutorials. We'll build a little markdown blog with data loading, actions, form validation, redirects, and more.</p>
     </docs-card>
   </a>
-  <a href="v1/api/remix" aria-label="Remix API">
+  <a href="tutorials/jokes" aria-label="Jokes App Tutorial">
     <docs-card>
-      <h4>Remix Package API</h4>
-      <p>This is probably the doc page you'll visit the most. It's got all of the Remix package exports that you'll use day-to-day in your app.</p>
+      <h4>Jokes App Deep Dive</h4> 
+      <p>Dive deep into Remix and full stack development with this app. It's backed by a SQL database, user authentication and session, and of course some modern UI finishes. You'll learn about nested routes, sessions, data loading, data mutations, progressive enhancement, and more. Get a feel for what a data-backed web app feels like with Remix.</p>
     </docs-card>
   </a>
 </docs-cards>

diff --git a/docs/pages/api-development-strategy.md b/docs/pages/api-development-strategy.md
@@ -1,6 +1,7 @@
 ---
 title: API Development Strategy
 description: Remix's strategy tp provide a smooth upgrade experience for application developers
+new: true
 ---
 
 # API Development Strategy