react-router 7.15.1 → 8.0.0-pre.0

package/docs/how-to/file-route-conventions.md

@@ -0,0 +1,410 @@
+---
+title: File Route Conventions
+---
+
+# File Route Conventions
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+The `@react-router/fs-routes` package enables file-convention based route config.
+
+## Setting up
+
+First install the `@react-router/fs-routes` package:
+
+```shellscript nonumber
+npm i @react-router/fs-routes
+```
+
+Then use it to provide route config in your `app/routes.ts` file:
+
+```tsx filename=app/routes.ts
+import { type RouteConfig } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default flatRoutes() satisfies RouteConfig;
+```
+
+Any modules in the `app/routes` directory will become routes in your application by default.
+The `ignoredRouteFiles` option allows you to specify files that should not be included as routes:
+
+```tsx filename=app/routes.ts
+import { type RouteConfig } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default flatRoutes({
+  ignoredRouteFiles: ["home.tsx"],
+}) satisfies RouteConfig;
+```
+
+This will look for routes in the `app/routes` directory by default, but this can be configured via the `rootDirectory` option which is relative to your app directory:
+
+```tsx filename=app/routes.ts
+import { type RouteConfig } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default flatRoutes({
+  rootDirectory: "file-routes",
+}) satisfies RouteConfig;
+```
+
+The rest of this guide will assume you're using the default `app/routes` directory.
+
+## Basic Routes
+
+The filename maps to the route's URL pathname, except for `_index.tsx` which is the [index route][index_route] for the [root route][root_route]. You can use `.js`, `.jsx`, `.ts` or `.tsx` file extensions.
+
+```text lines=[3-4]
+app/
+├── routes/
+│   ├── _index.tsx
+│   └── about.tsx
+└── root.tsx
+```
+
+| URL      | Matched Routes          |
+| -------- | ----------------------- |
+| `/`      | `app/routes/_index.tsx` |
+| `/about` | `app/routes/about.tsx`  |
+
+Note that these routes will be rendered in the outlet of `app/root.tsx` because of [nested routing][nested_routing].
+
+## Dot Delimiters
+
+Adding a `.` to a route filename will create a `/` in the URL.
+
+```text lines=[5-7]
+ app/
+├── routes/
+│   ├── _index.tsx
+│   ├── about.tsx
+│   ├── concerts.trending.tsx
+│   ├── concerts.salt-lake-city.tsx
+│   └── concerts.san-diego.tsx
+└── root.tsx
+```
+
+| URL                        | Matched Route                            |
+| -------------------------- | ---------------------------------------- |
+| `/`                        | `app/routes/_index.tsx`                  |
+| `/about`                   | `app/routes/about.tsx`                   |
+| `/concerts/trending`       | `app/routes/concerts.trending.tsx`       |
+| `/concerts/salt-lake-city` | `app/routes/concerts.salt-lake-city.tsx` |
+| `/concerts/san-diego`      | `app/routes/concerts.san-diego.tsx`      |
+
+The dot delimiter also creates nesting, see the [nesting section][nested_routes] for more information.
+
+## Dynamic Segments
+
+Usually your URLs aren't static but data-driven. Dynamic segments allow you to match segments of the URL and use that value in your code. You create them with the `$` prefix.
+
+```text lines=[5]
+ app/
+├── routes/
+│   ├── _index.tsx
+│   ├── about.tsx
+│   ├── concerts.$city.tsx
+│   └── concerts.trending.tsx
+└── root.tsx
+```
+
+| URL                        | Matched Route                      |
+| -------------------------- | ---------------------------------- |
+| `/`                        | `app/routes/_index.tsx`            |
+| `/about`                   | `app/routes/about.tsx`             |
+| `/concerts/trending`       | `app/routes/concerts.trending.tsx` |
+| `/concerts/salt-lake-city` | `app/routes/concerts.$city.tsx`    |
+| `/concerts/san-diego`      | `app/routes/concerts.$city.tsx`    |
+
+The value will be parsed from the URL and passed to various APIs. We call these values "URL Parameters". The most useful places to access the URL params are in [loaders] and [actions].
+
+```tsx
+export async function loader({ params }) {
+  return fakeDb.getAllConcertsForCity(params.city);
+}
+```
+
+You'll note the property name on the `params` object maps directly to the name of your file: `$city.tsx` becomes `params.city`.
+
+Routes can have multiple dynamic segments, like `concerts.$city.$date`, both are accessed on the params object by name:
+
+```tsx
+export async function loader({ params }) {
+  return fake.db.getConcerts({
+    date: params.date,
+    city: params.city,
+  });
+}
+```
+
+See the [routing guide][routing_guide] for more information.
+
+## Nested Routes
+
+Nested Routing is the general idea of coupling segments of the URL to component hierarchy and data. You can read more about it in the [Routing Guide][nested_routing].
+
+You create nested routes with [dot delimiters][dot_delimiters]. If the filename before the `.` matches another route filename, it automatically becomes a child route to the matching parent. Consider these routes:
+
+```text lines=[5-8]
+ app/
+├── routes/
+│   ├── _index.tsx
+│   ├── about.tsx
+│   ├── concerts._index.tsx
+│   ├── concerts.$city.tsx
+│   ├── concerts.trending.tsx
+│   └── concerts.tsx
+└── root.tsx
+```
+
+All the routes that start with `app/routes/concerts.` will be child routes of `app/routes/concerts.tsx` and render inside the [parent route's outlet][nested_routing].
+
+| URL                        | Matched Route                      | Layout                    |
+| -------------------------- | ---------------------------------- | ------------------------- |
+| `/`                        | `app/routes/_index.tsx`            | `app/root.tsx`            |
+| `/about`                   | `app/routes/about.tsx`             | `app/root.tsx`            |
+| `/concerts`                | `app/routes/concerts._index.tsx`   | `app/routes/concerts.tsx` |
+| `/concerts/trending`       | `app/routes/concerts.trending.tsx` | `app/routes/concerts.tsx` |
+| `/concerts/salt-lake-city` | `app/routes/concerts.$city.tsx`    | `app/routes/concerts.tsx` |
+
+Note you typically want to add an index route when you add nested routes so that something renders inside the parent's outlet when users visit the parent URL directly.
+
+For example, if the URL is `/concerts/salt-lake-city` then the UI hierarchy will look like this:
+
+```tsx
+<Root>
+  <Concerts>
+    <City />
+  </Concerts>
+</Root>
+```
+
+## Nested URLs without Layout Nesting
+
+Sometimes you want the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment:
+
+```text lines=[8]
+ app/
+├── routes/
+│   ├── _index.tsx
+│   ├── about.tsx
+│   ├── concerts.$city.tsx
+│   ├── concerts.trending.tsx
+│   ├── concerts.tsx
+│   └── concerts_.mine.tsx
+└── root.tsx
+```
+
+| URL                        | Matched Route                      | Layout                    |
+| -------------------------- | ---------------------------------- | ------------------------- |
+| `/`                        | `app/routes/_index.tsx`            | `app/root.tsx`            |
+| `/about`                   | `app/routes/about.tsx`             | `app/root.tsx`            |
+| `/concerts/mine`           | `app/routes/concerts_.mine.tsx`    | `app/root.tsx`            |
+| `/concerts/trending`       | `app/routes/concerts.trending.tsx` | `app/routes/concerts.tsx` |
+| `/concerts/salt-lake-city` | `app/routes/concerts.$city.tsx`    | `app/routes/concerts.tsx` |
+
+Note that `/concerts/mine` does not nest with `app/routes/concerts.tsx` anymore, but `app/root.tsx`. The `trailing_` underscore creates a path segment, but it does not create layout nesting.
+
+Think of the `trailing_` underscore as the long bit at the end of your parent's signature, writing you out of the will, removing the segment that follows from the layout nesting.
+
+## Nested Layouts without Nested URLs
+
+We call these <a name="pathless-routes"><b>Pathless Routes</b></a>
+
+Sometimes you want to share a layout with a group of routes without adding any path segments to the URL. A common example is a set of authentication routes that have a different header/footer than the public pages or the logged in app experience. You can do this with a `_leading` underscore.
+
+```text lines=[3-5]
+ app/
+├── routes/
+│   ├── _auth.login.tsx
+│   ├── _auth.register.tsx
+│   ├── _auth.tsx
+│   ├── _index.tsx
+│   ├── concerts.$city.tsx
+│   └── concerts.tsx
+└── root.tsx
+```
+
+| URL                        | Matched Route                   | Layout                    |
+| -------------------------- | ------------------------------- | ------------------------- |
+| `/`                        | `app/routes/_index.tsx`         | `app/root.tsx`            |
+| `/login`                   | `app/routes/_auth.login.tsx`    | `app/routes/_auth.tsx`    |
+| `/register`                | `app/routes/_auth.register.tsx` | `app/routes/_auth.tsx`    |
+| `/concerts`                | `app/routes/concerts.tsx`       | `app/routes/concerts.tsx` |
+| `/concerts/salt-lake-city` | `app/routes/concerts.$city.tsx` | `app/routes/concerts.tsx` |
+
+Think of the `_leading` underscore as a blanket you're pulling over the filename, hiding the filename from the URL.
+
+## Optional Segments
+
+Wrapping a route segment in parentheses will make the segment optional.
+
+```text lines=[3-5]
+ app/
+├── routes/
+│   ├── ($lang)._index.tsx
+│   ├── ($lang).$productId.tsx
+│   └── ($lang).categories.tsx
+└── root.tsx
+```
+
+| URL                        | Matched Route                       |
+| -------------------------- | ----------------------------------- |
+| `/`                        | `app/routes/($lang)._index.tsx`     |
+| `/categories`              | `app/routes/($lang).categories.tsx` |
+| `/en/categories`           | `app/routes/($lang).categories.tsx` |
+| `/fr/categories`           | `app/routes/($lang).categories.tsx` |
+| `/american-flag-speedo`    | `app/routes/($lang)._index.tsx`     |
+| `/en/american-flag-speedo` | `app/routes/($lang).$productId.tsx` |
+| `/fr/american-flag-speedo` | `app/routes/($lang).$productId.tsx` |
+
+You may wonder why `/american-flag-speedo` is matching the `($lang)._index.tsx` route instead of `($lang).$productId.tsx`. This is because when you have an optional dynamic param segment followed by another dynamic param, it cannot reliably be determined if a single-segment URL such as `/american-flag-speedo` should match `/:lang` `/:productId`. Optional segments match eagerly and thus it will match `/:lang`. If you have this type of setup it's recommended to look at `params.lang` in the `($lang)._index.tsx` loader and redirect to `/:lang/american-flag-speedo` for the current/default language if `params.lang` is not a valid language code.
+
+## Splat Routes
+
+While [dynamic segments][dynamic_segments] match a single path segment (the stuff between two `/` in a URL), a splat route will match the rest of a URL, including the slashes.
+
+```text lines=[4,6]
+ app/
+├── routes/
+│   ├── _index.tsx
+│   ├── $.tsx
+│   ├── about.tsx
+│   └── files.$.tsx
+└── root.tsx
+```
+
+| URL                                          | Matched Route            |
+| -------------------------------------------- | ------------------------ |
+| `/`                                          | `app/routes/_index.tsx`  |
+| `/about`                                     | `app/routes/about.tsx`   |
+| `/beef/and/cheese`                           | `app/routes/$.tsx`       |
+| `/files`                                     | `app/routes/files.$.tsx` |
+| `/files/talks/react-conf_old.pdf`            | `app/routes/files.$.tsx` |
+| `/files/talks/react-conf_final.pdf`          | `app/routes/files.$.tsx` |
+| `/files/talks/react-conf-FINAL-MAY_2024.pdf` | `app/routes/files.$.tsx` |
+
+Similar to dynamic route parameters, you can access the value of the matched path on the splat route's `params` with the `"*"` key.
+
+```tsx filename=app/routes/files.$.tsx
+export async function loader({ params }) {
+  const filePath = params["*"];
+  return fake.getFileInfo(filePath);
+}
+```
+
+## Catch-all Route
+
+To create a route that will match any requests that don't match other defined routes (such as a 404 page), create a file named `$.tsx` within your routes directory:
+
+| URL                            | Matched Route           |
+| ------------------------------ | ----------------------- |
+| `/`                            | `app/routes/_index.tsx` |
+| `/about`                       | `app/routes/about.tsx`  |
+| `/any-invalid-path-will-match` | `app/routes/$.tsx`      |
+
+By default the matched route will return a 200 response, so be sure to modify your catchall route to return a 404 instead:
+
+```tsx filename=app/routes/$.tsx
+export async function loader() {
+  return data({}, 404);
+}
+```
+
+## Escaping Special Characters
+
+If you want one of the special characters used for these route conventions to actually be a part of the URL, you can escape the conventions with `[]` characters. This can be especially helpful for [resource routes][resource_routes] that include an extension in the URL.
+
+| Filename                            | URL                 |
+| ----------------------------------- | ------------------- |
+| `app/routes/sitemap[.]xml.tsx`      | `/sitemap.xml`      |
+| `app/routes/[sitemap.xml].tsx`      | `/sitemap.xml`      |
+| `app/routes/weird-url.[_index].tsx` | `/weird-url/_index` |
+| `app/routes/dolla-bills-[$].tsx`    | `/dolla-bills-$`    |
+| `app/routes/[[so-weird]].tsx`       | `/[so-weird]`       |
+| `app/routes/reports.$id[.pdf].ts`   | `/reports/123.pdf`  |
+
+## Folders for Organization
+
+Routes can also be folders with a `route.tsx` file inside defining the route module. The rest of the files in the folder will not become routes. This allows you to organize your code closer to the routes that use them instead of repeating the feature names across other folders.
+
+The files inside a folder have no meaning for the route paths, the route path is completely defined by the folder name.
+
+Consider these routes:
+
+```text
+ app/
+├── routes/
+│   ├── _landing._index.tsx
+│   ├── _landing.about.tsx
+│   ├── _landing.tsx
+│   ├── app._index.tsx
+│   ├── app.projects.tsx
+│   ├── app.tsx
+│   └── app_.projects.$id.roadmap.tsx
+└── root.tsx
+```
+
+Some, or all of them can be folders holding their own `route` module inside.
+
+```text
+app/
+├── routes/
+│   ├── _landing._index/
+│   │   ├── route.tsx
+│   │   └── scroll-experience.tsx
+│   ├── _landing.about/
+│   │   ├── employee-profile-card.tsx
+│   │   ├── get-employee-data.server.ts
+│   │   ├── route.tsx
+│   │   └── team-photo.jpg
+│   ├── _landing/
+│   │   ├── footer.tsx
+│   │   ├── header.tsx
+│   │   └── route.tsx
+│   ├── app._index/
+│   │   ├── route.tsx
+│   │   └── stats.tsx
+│   ├── app.projects/
+│   │   ├── get-projects.server.ts
+│   │   ├── project-buttons.tsx
+│   │   ├── project-card.tsx
+│   │   └── route.tsx
+│   ├── app/
+│   │   ├── footer.tsx
+│   │   ├── primary-nav.tsx
+│   │   └── route.tsx
+│   ├── app_.projects.$id.roadmap/
+│   │   ├── chart.tsx
+│   │   ├── route.tsx
+│   │   └── update-timeline.server.ts
+│   └── contact-us.tsx
+└── root.tsx
+```
+
+Note that when you turn a route module into a folder, the route module becomes `folder/route.tsx`, all other modules in the folder will not become routes. For example:
+
+```
+# these are the same route:
+app/routes/app.tsx
+app/routes/app/route.tsx
+
+# as are these
+app/routes/app._index.tsx
+app/routes/app._index/route.tsx
+```
+
+[route-config-file]: ../start/framework/routing#configuring-routes
+[loaders]: ../start/framework/data-loading
+[actions]: ../start/framework/actions
+[routing_guide]: ../start/framework/routing
+[root_route]: ../start/framework/route-module
+[index_route]: ../start/framework/routing#index-routes
+[nested_routing]: ../start/framework/routing#nested-routes
+[nested_routes]: #nested-routes
+[dot_delimiters]: #dot-delimiters
+[dynamic_segments]: #dynamic-segments
+[resource_routes]: ../how-to/resource-routes

package/docs/how-to/file-uploads.md

@@ -0,0 +1,217 @@
+---
+title: File Uploads
+---
+
+# File Uploads
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+_Thank you to David Adams for [writing an original guide](https://programmingarehard.com/2024/09/06/remix-file-uploads-updated.html/) on which this doc is based. You can refer to it for even more examples._
+
+## Basic File Upload
+
+### 1. Setup some routes
+
+You can setup your routes however you like. This example uses the following structure:
+
+```ts filename=routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+
+export default [
+  // ... other routes
+  route("user/:id", "pages/user-profile.tsx", [
+    route("avatar", "api/avatar.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+### 2. Add the form data parser
+
+`form-data-parser` is a wrapper around `request.formData()` that provides streaming support for handling file uploads.
+
+```shellscript
+npm i @remix-run/form-data-parser
+```
+
+[See the `form-data-parser` docs for more information][form-data-parser]
+
+### 3. Create a route with an upload action
+
+The `parseFormData` function takes an `uploadHandler` function as an argument. This function will be called for each file upload in the form.
+
+<docs-warning>
+
+You must set the form's `enctype` to `multipart/form-data` for file uploads to work.
+
+</docs-warning>
+
+```tsx filename=pages/user-profile.tsx
+import {
+  type FileUpload,
+  parseFormData,
+} from "@remix-run/form-data-parser";
+import type { Route } from "./+types/user-profile";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const uploadHandler = async (fileUpload: FileUpload) => {
+    if (fileUpload.fieldName === "avatar") {
+      // process the upload and return a File
+    }
+  };
+
+  const formData = await parseFormData(
+    request,
+    uploadHandler,
+  );
+  // 'avatar' has already been processed at this point
+  const file = formData.get("avatar");
+}
+
+export default function Component() {
+  return (
+    <form method="post" encType="multipart/form-data">
+      <input type="file" name="avatar" />
+      <button>Submit</button>
+    </form>
+  );
+}
+```
+
+## Local Storage Implementation
+
+### 1. Add the storage package
+
+`file-storage` is a key/value interface for storing [File objects][file] in JavaScript. Similar to how `localStorage` allows you to store key/value pairs of strings in the browser, file-storage allows you to store key/value pairs of files on the server.
+
+```shellscript
+npm i @remix-run/file-storage
+```
+
+[See the `file-storage` docs for more information][file-storage]
+
+### 2. Create a storage configuration
+
+Create a file that exports a `LocalFileStorage` instance to be used by different routes.
+
+```ts filename=avatar-storage.server.ts
+import { LocalFileStorage } from "@remix-run/file-storage/local";
+
+export const fileStorage = new LocalFileStorage(
+  "./uploads/avatars",
+);
+
+export function getStorageKey(userId: string) {
+  return `user-${userId}-avatar`;
+}
+```
+
+### 3. Implement the upload handler
+
+Update the form's `action` to store files in the `fileStorage` instance.
+
+```tsx filename=pages/user-profile.tsx
+import {
+  type FileUpload,
+  parseFormData,
+} from "@remix-run/form-data-parser";
+import {
+  fileStorage,
+  getStorageKey,
+} from "~/avatar-storage.server";
+import type { Route } from "./+types/user-profile";
+
+export async function action({
+  request,
+  params,
+}: Route.ActionArgs) {
+  async function uploadHandler(fileUpload: FileUpload) {
+    if (
+      fileUpload.fieldName === "avatar" &&
+      fileUpload.type.startsWith("image/")
+    ) {
+      let storageKey = getStorageKey(params.id);
+
+      // FileUpload objects are not meant to stick around for very long (they are
+      // streaming data from the request.body); store them as soon as possible.
+      await fileStorage.set(storageKey, fileUpload);
+
+      // Return a File for the FormData object. This is a LazyFile that knows how
+      // to access the file's content if needed (using e.g. file.stream()) but
+      // waits until it is requested to actually read anything.
+      return fileStorage.get(storageKey);
+    }
+  }
+
+  const formData = await parseFormData(
+    request,
+    uploadHandler,
+  );
+}
+
+export default function UserPage({
+  actionData,
+  params,
+}: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>User {params.id}</h1>
+      <form
+        method="post"
+        // The form's enctype must be set to "multipart/form-data" for file uploads
+        encType="multipart/form-data"
+      >
+        <input type="file" name="avatar" accept="image/*" />
+        <button>Submit</button>
+      </form>
+
+      <img
+        src={`/user/${params.id}/avatar`}
+        alt="user avatar"
+      />
+    </div>
+  );
+}
+```
+
+### 4. Add a route to serve the uploaded file
+
+Create a [resource route][resource-route] that streams the file as a response.
+
+```tsx filename=api/avatar.tsx
+import {
+  fileStorage,
+  getStorageKey,
+} from "~/avatar-storage.server";
+import type { Route } from "./+types/avatar";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const storageKey = getStorageKey(params.id);
+  const file = await fileStorage.get(storageKey);
+
+  if (!file) {
+    throw new Response("User avatar not found", {
+      status: 404,
+    });
+  }
+
+  return new Response(file.stream(), {
+    headers: {
+      "Content-Type": file.type,
+      "Content-Disposition": `attachment; filename=${file.name}`,
+    },
+  });
+}
+```
+
+[form-data-parser]: https://www.npmjs.com/package/@remix-run/form-data-parser
+[file-storage]: https://www.npmjs.com/package/@remix-run/file-storage
+[file]: https://developer.mozilla.org/en-US/docs/Web/API/File
+[resource-route]: ../how-to/resource-routes