From aaa9be932917052dc5b4caf32529c02f88d3beaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20De=20Boey?= Date: Thu, 17 Aug 2023 21:58:20 +0200 Subject: [PATCH 1/4] docs: small updates --- .eslintrc.js | 2 + CONTRIBUTING.md | 2 +- README.md | 4 +- docs/components/await.md | 24 +- docs/components/form.md | 75 ++--- docs/components/link.md | 14 +- docs/components/links.md | 6 +- docs/components/live-reload.md | 4 +- docs/components/meta.md | 6 +- docs/components/nav-link.md | 18 +- docs/components/scripts.md | 4 +- docs/components/scroll-restoration.md | 22 +- docs/discussion/concurrency.md | 22 +- docs/discussion/data-flow.md | 56 ++-- docs/discussion/form-vs-fetcher.md | 87 +++--- docs/discussion/introduction.md | 16 +- docs/discussion/pending-ui.md | 55 ++-- docs/discussion/progressive-enhancement.md | 12 +- docs/discussion/react-router.md | 12 +- docs/discussion/resubmissions.md | 10 +- docs/discussion/routes.md | 121 ++++---- docs/discussion/runtimes.md | 30 +- docs/discussion/server-vs-client.md | 43 ++- docs/discussion/state-management.md | 91 ++++--- docs/file-conventions/-client.md | 9 +- docs/file-conventions/-server.md | 7 +- docs/file-conventions/asset-imports.md | 12 +- docs/file-conventions/entry.client.md | 8 +- docs/file-conventions/remix-config.md | 50 ++-- docs/file-conventions/routes.md | 303 ++++++++++----------- docs/guides/contributing.md | 64 ++--- docs/guides/errors.md | 58 ++-- docs/guides/faq.md | 14 +- docs/guides/form-validation.md | 32 ++- docs/guides/gotchas.md | 40 +-- docs/guides/index-query-param.md | 52 ++++ docs/guides/local-tls.md | 17 +- docs/guides/manual-mode.md | 23 +- docs/guides/migrating-react-router-app.md | 26 +- docs/guides/streaming.md | 64 +++-- docs/guides/templates.md | 70 ++--- docs/hooks/use-action-data.md | 22 +- docs/hooks/use-async-error.md | 14 +- docs/hooks/use-async-value.md | 10 +- docs/hooks/use-before-unload.md | 4 +- docs/hooks/use-fetcher.md | 39 +-- docs/hooks/use-fetchers.md | 19 +- docs/hooks/use-form-action.md | 5 +- docs/hooks/use-href.md | 10 +- docs/hooks/use-loader-data.md | 20 +- docs/hooks/use-location.md | 5 +- docs/index.md | 12 +- docs/other-api/dev.md | 135 ++++----- docs/other-api/serve.md | 30 +- docs/route/action.md | 16 +- docs/route/loader.md | 11 +- docs/route/meta.md | 10 +- docs/route/should-revalidate.md | 6 +- docs/start/community.md | 2 +- docs/start/future-flags.md | 6 +- docs/start/quickstart.md | 20 +- docs/start/tutorial.md | 92 ++++--- docs/start/v2.md | 277 ++++++++++--------- docs/styling/bundling.md | 16 +- docs/styling/css-imports.md | 3 +- docs/styling/css.md | 72 +++-- docs/styling/postcss.md | 73 ++--- docs/styling/tailwind.md | 15 +- docs/styling/vanilla-extract.md | 2 +- docs/tutorials/blog.md | 30 +- docs/tutorials/jokes.md | 23 +- packages/remix-dev/config.ts | 4 +- 72 files changed, 1417 insertions(+), 1171 deletions(-) create mode 100644 docs/guides/index-query-param.md diff --git a/.eslintrc.js b/.eslintrc.js index 20bb1250efc..cf59e693bea 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -52,6 +52,8 @@ module.exports = { "newlines-between": "always", }, ], + + "react/jsx-no-leaked-render": [WARN, { validStrategies: ["ternary"] }], }, }, ], diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f28ddb68aa..f96a9e16d21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -Please see [our guide to contributing](docs/pages/contributing.md). +Please see [our guide to contributing](docs/guides/contributing). diff --git a/README.md b/README.md index 2ecd384faea..10cfb0c363d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ We are happy you're here! [Remix](https://remix.run) is a full stack web framework that lets you focus on the user interface and work back through web fundamentals to deliver a fast, slick, and resilient user experience that deploys to any Node.js server and even non-Node.js environments at the edge like Cloudflare Workers. -Want to know more? Read the [Technical Explanation of Remix](https://remix.run/pages/technical-explanation) +Want to know more? Read the [Technical Explanation of Remix](https://remix.run/discussion/introduction) This repository contains the Remix source code. This repo is a work in progress, so we appreciate your patience as we figure things out. @@ -19,7 +19,7 @@ The documentation is automatically generated on each release from the files in ## Contributing -If you're interested in contributing code and/or documentation, please see [our guide to contributing](docs/pages/contributing.md). +If you're interested in contributing code and/or documentation, please see [our guide to contributing](docs/guides/contributing). ## Code of Conduct diff --git a/docs/components/await.md b/docs/components/await.md index 7756fb2a667..63b185b8798 100644 --- a/docs/components/await.md +++ b/docs/components/await.md @@ -1,13 +1,12 @@ --- title: Await -toc: false --- # `` -To get started with streaming data, check out the [Streaming Guide][streaming-guide-2]. +To get started with streaming data, check out the [Streaming Guide][streaming_guide]. -The `` component is responsible for resolving deferred loader promises accessed from [`useLoaderData`][useloaderdata]. +The `` component is responsible for resolving deferred loader promises accessed from [`useLoaderData`][use_loader_data]. ```tsx import { Await } from "@remix-run/react"; @@ -23,13 +22,13 @@ import { Await } from "@remix-run/react"; ### `resolve` -The resolve prop takes a promise from [`useLoaderData`][useloaderdata] to resolve when the data has streamed in. +The resolve prop takes a promise from [`useLoaderData`][use_loader_data] to resolve when the data has streamed in. ```tsx ``` -When the promise is not resolve, a parent suspense boundary's fallback will be rendered. +When the promise is not resolved, a parent suspense boundary's fallback will be rendered. ```tsx Loading...}> @@ -37,7 +36,7 @@ When the promise is not resolve, a parent suspense boundary's fallback will be r ``` -When the promise is resolved, the children will be rendered. +When the promise is resolved, the `children` will be rendered. ### `children` @@ -49,7 +48,7 @@ The `children` can be a render callback or a React element. ``` -If the `children` props is a React element, the resolved value will be accessible through `useAsyncValue` in the subtree. +If the `children` props is a React element, the resolved value will be accessible through [`useAsyncValue`][use_async_value] in the subtree. ```tsx @@ -74,7 +73,7 @@ The `errorElement` prop can be used to render an error boundary when the promise Oops!} /> ``` -The error can be accessed in the sub tree with [`useAsyncError`][use-async-error] +The error can be accessed in the subtree with [`useAsyncError`][use_async_error] ```tsx } /> @@ -89,8 +88,7 @@ function SomeChild() { } ``` -[defer]: ../utils/defer -[streaming-guide]: ../guides/streaming -[useloaderdata]: ../hooks/use-loader-data -[streaming-guide-2]: ../guides/streaming -[use-async-error]: ../hooks/use-async-error +[streaming_guide]: ../guides/streaming +[use_loader_data]: ../hooks/use-loader-data +[use_async_value]: ../hooks/use-async-value +[use_async_error]: ../hooks/use-async-error diff --git a/docs/components/form.md b/docs/components/form.md index b1e7d887331..1355f6f97a5 100644 --- a/docs/components/form.md +++ b/docs/components/form.md @@ -4,16 +4,16 @@ title: Form # `
` -A progressively enhanced HTML `` wrapper, useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use [``][fetcher-form]. +A progressively enhanced HTML [``][form_element] wrapper, useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use [``][fetcher_form]. ```tsx import { Form } from "@remix-run/react"; function NewEvent() { return ( - - - + + + ); } @@ -25,17 +25,17 @@ function NewEvent() { The URL to submit the form data to. -If `undefined`, the action defaults to the closest route in context. If a parent route renders a `
` but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native `` that will always point to the full URL. +If `undefined`, this defaults to the closest route in context. If a parent route renders a `` but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native [``][form_element] that will always point to the full URL. ### `method` -This determines the [HTTP verb][http-verb] to be used: get, post, put, patch, delete. The default is "get". +This determines the [HTTP verb][http_verb] to be used: `DELETE`, `GET`, `PATCH`, `POST`, and `PUT`. The default is `GET`. ```tsx ``` -Native `` only supports GET and POST, so you should avoid the other verbs if you'd like to support [progressive enhancement][progressive-enhancement] +Native [``][form_element] only supports `GET` and `POST`, so you should avoid the other verbs if you'd like to support [progressive enhancement][progressive_enhancement] ### `encType` @@ -47,6 +47,14 @@ The encoding type to use for the form submission. Defaults to `application/x-www-form-urlencoded`, use `multipart/form-data` for file uploads. +### `preventScrollReset` + +If you are using [``][scroll_restoration_component], this lets you prevent the scroll position from being reset to the top of the window when the form is submitted. + +```tsx + +``` + ### `replace` Replaces the current entry in the history stack, instead of pushing the new entry. @@ -63,7 +71,7 @@ If true, it will submit the form with the browser instead of client side routing ``` -This is recommended over ``. When the `action` prop is omitted, `` and `` will sometimes call different actions depending on what the current URL is since `` uses the current URL as the default, but `` uses the URL for the route the form is rendered in. +This is recommended over [``][form_element]. When the `action` prop is omitted, `` and `` will sometimes call different actions depending on what the current URL is since `` uses the current URL as the default, but `` uses the URL for the route the form is rendered in. ## Notes @@ -82,39 +90,40 @@ Because index routes and their parent route share the same URL, the `?index` par See also: -- [`?index` query param][index query param] +- [`?index` query param][index_query_param] ## Additional Resources **Videos:** -- [Data Mutations with Form + action][data-mutations-with-form-action] -- [Multiple Forms and Single Button Mutations][multiple-forms-and-single-button-mutations] -- [Clearing Inputs After Form Submissions][clearing-inputs-after-form-submissions] +- [Data Mutations with Form + action][data_mutations_with_form_action] +- [Multiple Forms and Single Button Mutations][multiple_forms_and_single_button_mutations] +- [Clearing Inputs After Form Submissions][clearing_inputs_after_form_submissions] **Related Discussions:** -- [Fullstack Data Flow][fullstack-data-flow] -- [Pending UI][pending-ui] -- [Form vs. Fetcher][form-vs-fetcher] +- [Fullstack Data Flow][fullstack_data_flow] +- [Pending UI][pending_ui] +- [Form vs. Fetcher][form_vs_fetcher] **Related APIs:** -- [`useNavigation`][usenavigation] -- [`useActionData`][useactiondata] -- [`useSubmit`][usesubmit] - -[index query param]: ../guides/routing#what-is-the-index-query-param -[usenavigation]: ../hooks/use-navigation -[useactiondata]: ../hooks/use-action-data -[usesubmit]: ../hooks/use-submit -[http-verb]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods -[rr-form]: https://reactrouter.com/components/form -[data-mutations-with-form-action]: https://www.youtube.com/watch?v=Iv25HAHaFDs&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 -[multiple-forms-and-single-button-mutations]: https://www.youtube.com/watch?v=w2i-9cYxSdc&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 -[clearing-inputs-after-form-submissions]: https://www.youtube.com/watch?v=bMLej7bg5Zo&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 -[fullstack-data-flow]: ../discussion/data-flow -[pending-ui]: ../discussion/pending-ui -[form-vs-fetcher]: ../discussion/form-vs-fetcher -[fetcher-form]: ../hooks/use-fetcher -[progressive-enhancement]: ../discussion/progressive-enhancement +- [`useActionData`][use_action_data] +- [`useNavigation`][use_navigation] +- [`useSubmit`][use_submit] + +[use_navigation]: ../hooks/use-navigation +[scroll_restoration_component]: ./scroll-restoration +[index_query_param]: ../guides/index-query-param +[http_verb]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods +[form_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form +[use_action_data]: ../hooks/use-action-data +[use_submit]: ../hooks/use-submit +[data_mutations_with_form_action]: https://www.youtube.com/watch?v=Iv25HAHaFDs&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 +[multiple_forms_and_single_button_mutations]: https://www.youtube.com/watch?v=w2i-9cYxSdc&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 +[clearing_inputs_after_form_submissions]: https://www.youtube.com/watch?v=bMLej7bg5Zo&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6 +[fullstack_data_flow]: ../discussion/data-flow +[pending_ui]: ../discussion/pending-ui +[form_vs_fetcher]: ../discussion/form-vs-fetcher +[fetcher_form]: ../hooks/use-fetcher#fetcherform +[progressive_enhancement]: ../discussion/progressive-enhancement diff --git a/docs/components/link.md b/docs/components/link.md index 4410b4d811b..72d7aa0a486 100644 --- a/docs/components/link.md +++ b/docs/components/link.md @@ -47,7 +47,7 @@ Because of this, if you are using `nav :last-child` you will need to use `nav :l ### `preventScrollReset` -If you are using [``][scroll-restoration], this lets you prevent the scroll position from being reset to the top of the window when the link is clicked. +If you are using [``][scroll_restoration_component], this lets you prevent the scroll position from being reset to the top of the window when the link is clicked. ```tsx @@ -56,11 +56,12 @@ If you are using [``][scroll-restoration], this lets you prev This does not prevent the scroll position from being restored when the user comes back to the location with the back/forward buttons, it just prevents the reset when the user clicks the link.
+ Discussion An example when you might want this behavior is a list of tabs that manipulate the url search params that aren't at the top of the page. You wouldn't want the scroll position to jump up to the top because it might scroll the toggled content out of the viewport! -``` +```text ┌─────────────────────────┐ │ ├──┐ │ │ │ @@ -137,15 +138,14 @@ Adds persistent client side routing state to the next location. The location state is accessed from the `location`. -```ts +```tsx function SomeComp() { const location = useLocation(); location.state; // { some: "value" } } ``` -This state is inaccessible on the server as it is implemented on top of [`history.state`][history-state]. +This state is inaccessible on the server as it is implemented on top of [`history.state`][history_state]. -[rr-link]: https://reactrouter.com/en/main/components/link -[scroll-restoration]: ./scroll-restoration -[history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state +[scroll_restoration_component]: ./scroll-restoration +[history_state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state diff --git a/docs/components/links.md b/docs/components/links.md index 10d8f3a4b0c..0a75f05db7d 100644 --- a/docs/components/links.md +++ b/docs/components/links.md @@ -5,9 +5,9 @@ toc: false # `` -The `` component renders all of the `` tags created by your route module [`links`][links] export. You should render it inside the `` of your HTML, usually in `app/root.tsx`. +The `` component renders all of the [``][link_element] tags created by your route module [`links`][links] export. You should render it inside the [``][head_element] of your HTML, usually in `app/root.tsx`. -```tsx filename=root.tsx lines=[7] +```tsx filename=app/root.tsx lines=[7] import { Links } from "@remix-run/react"; export default function Root() { @@ -22,4 +22,6 @@ export default function Root() { } ``` +[link_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link +[head_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head [links]: ../route/links diff --git a/docs/components/live-reload.md b/docs/components/live-reload.md index 912e8617b8a..0564a33a5c4 100644 --- a/docs/components/live-reload.md +++ b/docs/components/live-reload.md @@ -5,9 +5,9 @@ toc: false # `` -This component connects your app to the Remix asset server and automatically reloads the page when files change in development. In production it renders `null`, so you can safely render it always in your root route. +This component connects your app to the Remix asset server and automatically reloads the page when files change in development. In production, it renders `null`, so you can safely render it always in your root route. -```tsx filename=root.tsx lines=[8] +```tsx filename=app/root.tsx lines=[8] import { LiveReload } from "@remix-run/react"; export default function Root() { diff --git a/docs/components/meta.md b/docs/components/meta.md index dad74218f87..2bbce034008 100644 --- a/docs/components/meta.md +++ b/docs/components/meta.md @@ -5,9 +5,9 @@ toc: false # `` -This component renders all of the `` tags created by your route module [`meta`][meta] export. You should render it inside the `` of your HTML, usually in `app/root.tsx`. +This component renders all of the [``][meta_element] tags created by your route module [`meta`][meta] export. You should render it inside the [``][head_element] of your HTML, usually in `app/root.tsx`. -```tsx filename=root.tsx lines=[7] +```tsx filename=app/root.tsx lines=[7] import { Meta } from "@remix-run/react"; export default function Root() { @@ -22,4 +22,6 @@ export default function Root() { } ``` +[meta_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta +[head_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head [meta]: ../route/meta diff --git a/docs/components/nav-link.md b/docs/components/nav-link.md index 0aeb8abb651..8a61855c87b 100644 --- a/docs/components/nav-link.md +++ b/docs/components/nav-link.md @@ -1,11 +1,10 @@ --- title: NavLink -toc: false --- # `` -Wraps [``][link-2] with additional props for styling active and pending states. +Wraps [``][link_component] with additional props for styling active and pending states. ```tsx import { NavLink } from "@remix-run/react"; @@ -24,7 +23,7 @@ import { NavLink } from "@remix-run/react"; ### `.active` -An `active` class is added to a `` component when it is active so you can use CSS to style it. +An `active` class is added to a `` component when it is active, so you can use CSS to style it. ```tsx @@ -38,7 +37,7 @@ a.active { ### `aria-current` -When a `NavLink` is active it will automatically apply `` to the underlying anchor tag. See [aria-current][aria-current] on MDN. +When a `NavLink` is active it will automatically apply `` to the underlying anchor tag. See [aria_current][aria_current] on MDN. ## Props @@ -89,7 +88,7 @@ Calls back with the active and pending states to allow customizing the content o ### `end` -The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the NavLinks's `to` path. If the URL is longer than `to`, it will no longer be considered active. +The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the `NavLinks`'s `to` path. If the URL is longer than `to`, it will no longer be considered active. | Link | URL | isActive | | ----------------------------- | ------------ | -------- | @@ -102,7 +101,7 @@ The `end` prop changes the matching logic for the `active` and `pending` states ### `caseSensitive` -Adding the `caseSensitive` prop changes the matching logic to make it case sensitive. +Adding the `caseSensitive` prop changes the matching logic to make it case-sensitive. | Link | URL | isActive | | -------------------------------------------- | ------------- | -------- | @@ -111,8 +110,7 @@ Adding the `caseSensitive` prop changes the matching logic to make it case sensi ### `` props -All other props of [``][link] are supported. +All other props of [``][link_component] are supported. -[aria-current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current -[link]: ./link -[link-2]: ./link +[link_component]: ./link +[aria_current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current diff --git a/docs/components/scripts.md b/docs/components/scripts.md index cb26376e569..c4fe4c15f49 100644 --- a/docs/components/scripts.md +++ b/docs/components/scripts.md @@ -7,7 +7,7 @@ toc: false This component renders the client runtime of your app. You should render it inside the `` of your HTML, usually in `app/root.tsx`. -```tsx filename=root.tsx lines=[8] +```tsx filename=app/root.tsx lines=[8] import { Scripts } from "@remix-run/react"; export default function Root() { @@ -23,5 +23,3 @@ export default function Root() { ``` If you don't render the `` component, your app will still work like a traditional web app without JavaScript, relying solely on HTML and browser behaviors. - -[meta]: ../route/meta diff --git a/docs/components/scroll-restoration.md b/docs/components/scroll-restoration.md index 350e79bbbea..93d8fffdffb 100644 --- a/docs/components/scroll-restoration.md +++ b/docs/components/scroll-restoration.md @@ -4,14 +4,14 @@ title: ScrollRestoration # `` -This component will emulate the browser's scroll restoration on location changes after loaders have completed. This ensures the scroll position is restored to the right spot, at the right time, even across domains. +This component will emulate the browser's scroll restoration on location changes after [`loader`][loader]s have completed. This ensures the scroll position is restored to the right spot, at the right time, even across domains. -You should only render one of these, right before the `` component. +You should only render one of these, right before the [``][scripts_component] component. -```tsx lines=[2,11] +```tsx lines=[3,11] import { - ScrollRestoration, Scripts, + ScrollRestoration, } from "@remix-run/react"; export default function Root() { @@ -43,6 +43,7 @@ Optional. Defines the key used to restore scroll positions. ```
+ Discussion Using `location.key` emulates the browser's default behavior. The user can navigate to the same URL multiple times in the stack and each entry gets its own scroll position to restore. @@ -93,7 +94,7 @@ Or you may want to only use the pathname for some paths, and use the normal beha ### `nonce` -`` renders an inline `