diff --git a/decisions/0001-use-npm-to-manage-npm-dependencies-for-deno-projects.md b/decisions/0001-use-npm-to-manage-npm-dependencies-for-deno-projects.md
new file mode 100644
index 0000000000..35a6ec0a36
--- /dev/null
+++ b/decisions/0001-use-npm-to-manage-npm-dependencies-for-deno-projects.md
@@ -0,0 +1,113 @@
+# Use `npm` to manage NPM dependencies for Deno projects
+
+Date: 2022-05-10
+
+Status: accepted
+
+## Context
+
+Deno has three ways to manage dependencies:
+
+1. Inlined URL imports: `import {...} from "https://deno.land/x/blah"`
+2. [deps.ts](https://deno.land/manual/examples/manage_dependencies)
+3. [Import maps](https://deno.land/manual/linking_to_external_code/import_maps)
+
+Additionally, NPM packages can be accessed as Deno modules via [Deno-friendly CDNs](https://deno.land/manual/node/cdns#deno-friendly-cdns) like https://esm.sh.
+
+Remix has some requirements around dependencies:
+
+- Remix treeshakes dependencies that are free of side-effects.
+- Remix sets the environment (dev/prod/test) across all code, including dependencies, at runtime via the `NODE_ENV` environment variable.
+- Remix depends on some NPM packages that should be specified as peer dependencies (notably, `react` and `react-dom`).
+
+### Treeshaking
+
+To optimize bundle size, Remix [treeshakes](https://esbuild.github.io/api/#tree-shaking) your app's code and dependencies.
+This also helps to separate browser code and server code.
+
+Under the hood, the Remix compiler uses [esbuild](https://esbuild.github.io).
+Like other bundlers, `esbuild` uses [`sideEffects` in `package.json` to determine when it is safe to eliminate unused imports](https://esbuild.github.io/api/#conditionally-injecting-a-file).
+
+Unfortunately, URL imports do not have a standard mechanism for marking packages as side-effect free.
+
+### Setting dev/prod/test environment
+
+Deno-friendly CDNs set the environment via a query parameter (e.g. `?dev`), not via an environment variable.
+That means changing environment requires changing the URL import in the source code.
+While you could use multiple import maps (`dev.json`, `prod.json`, etc...) to workaround this, import maps have other limitations:
+
+- standard tooling for managing import maps is not available
+- import maps are not composeable, so any dependencies that use import maps must be manually accounted for
+
+### Specifying peer dependencies
+
+Even if import maps were perfected, CDNs compile each dependency in isolation.
+That means that specifying peer dependencies becomes tedious and error-prone as the user needs to:
+
+- determine which dependencies themselves depend on `react` (or other similar peer dependency), even if indirectly.
+- manually figure out which `react` version works across _all_ of these dependencies
+- set that version for `react` as a query parameter in _all_ of the URLs for the identified dependencies
+
+If any dependencies change (added, removed, version change),
+the user must repeat all of these steps again.
+
+## Decision
+
+### Use `npm` to manage NPM dependencies for Deno
+
+Do not use Deno-friendly CDNs for NPM dependencies in Remix projects using Deno.
+
+Use `npm` and `node_modules/` to manage NPM dependencies like `react` for Remix projects, even when using Deno with Remix.
+
+Deno module dependencies (e.g. from `https://deno.land`) can still be managed via URL imports.
+
+### Allow URL imports
+
+Remix will preserve any URL imports in the built bundles as external dependencies,
+letting your browser runtime and server runtime handle them accordingly.
+That means that you may:
+
+- use URL imports for the browser
+- use URL imports for the server, if your server runtime supports it
+
+For example, Node will throw errors for URL imports, while Deno will resolve URL imports as normal.
+
+### Do not support import maps
+
+Remix will not yet support import maps.
+
+## Consequences
+
+- URL imports will not be treeshaken.
+- Users can specify environment via the `NODE_ENV` environment variable at runtime.
+- Users won't have to do error-prone, manual dependency resolution.
+
+### VS Code type hints
+
+Users may configure an import map for the [Deno extension for VS Code](denoland.vscode-deno) to enable type hints for NPM-managed dependencies within their Deno editor:
+
+`.vscode/resolve_npm_imports_in_deno.json`
+
+```json
+{
+  "// This import map is used solely for the denoland.vscode-deno extension.": "",
+  "// Remix does not support import maps.": "",
+  "// Dependency management is done through `npm` and `node_modules/` instead.": "",
+  "// Deno-only dependencies may be imported via URL imports (without using import maps).": "",
+
+  "imports": {
+    "react": "https://esm.sh/react@18.0.0",
+    "react-dom": "https://esm.sh/react-dom@18.0.0",
+    "react-dom/server": "https://esm.sh/react-dom@18.0.0/server"
+  }
+}
+```
+
+`.vscode/settings.json`
+
+```json
+{
+  "deno.enable": true,
+  "deno.importMap": "./.vscode/resolve_npm_imports_in_deno.json"
+}
+```
diff --git a/decisions/0002-do-not-clone-request.md b/decisions/0002-do-not-clone-request.md
new file mode 100644
index 0000000000..30f599f7f0
--- /dev/null
+++ b/decisions/0002-do-not-clone-request.md
@@ -0,0 +1,19 @@
+# Do not clone request
+
+Date: 2022-05-13
+
+Status: accepted
+
+## Context
+
+To allow multiple loaders / actions to read the body of a request, we have been cloning the request before forwarding it to user-code. This is not the best thing to do as some runtimes will begin buffering the body to allow for multiple consumers. It also goes against "the platform" that states a request body should only be consumed once.
+
+## Decision
+
+Do not clone requests before they are passed to user-code (actions, handleDocumentRequest, handleDataRequest), and remove body from request passed to loaders. Loaders should be thought of as a "GET" / "HEAD" request handler. These request methods are not allowed to have a body, therefore you should not be reading it in your Remix loader function.
+
+## Consequences
+
+Loaders always receive a null body for the request.
+
+If you are reading the request body in both an action and handleDocumentRequest or handleDataRequest this will now fail as the body will have already been read. If you wish to continue reading the request body in multiple places for a single request against recommendations, consider using `.clone()` before reading it; just know this comes with tradeoffs.
diff --git a/decisions/0003-infer-types-for-useloaderdata-and-useactiondata-from-loader-and-action-via-generics.md b/decisions/0003-infer-types-for-useloaderdata-and-useactiondata-from-loader-and-action-via-generics.md
new file mode 100644
index 0000000000..1959f16183
--- /dev/null
+++ b/decisions/0003-infer-types-for-useloaderdata-and-useactiondata-from-loader-and-action-via-generics.md
@@ -0,0 +1,230 @@
+# Infer types for `useLoaderData` and `useActionData` from `loader` and `action` via generics
+
+Date: 2022-07-11
+
+Status: accepted
+
+## Context
+
+Goal: End-to-end type safety for `useLoaderData` and `useActionData` with great Developer Experience (DX)
+
+Related discussions:
+
+- [remix-run/remix#1254](https://github.com/remix-run/remix/pull/1254)
+- [remix-run/remix#3276](https://github.com/remix-run/remix/pull/3276)
+
+---
+
+In Remix v1.6.4, types for both `useLoaderData` and `useActionData` are parameterized with a generic:
+
+```tsx
+type MyLoaderData = {
+  /* ... */
+};
+type MyActionData = {
+  /* ... */
+};
+
+export default function Route() {
+  const loaderData = useLoaderData<MyLoaderData>();
+  const actionData = useActionData<MyActionData>();
+  return <div>{/* ... */}</div>;
+}
+```
+
+For end-to-end type safety, it is then the user's responsability to make sure that `loader` and `action` also use the same type in the `json` generic:
+
+```ts
+export const loader: LoaderFunction = () => {
+  return json<MyLoaderData>({
+    /* ... */
+  });
+};
+
+export const action: ActionFunction = () => {
+  return json<MyActionData>({
+    /* ... */
+  });
+};
+```
+
+### Diving into `useLoaderData`'s and `useActionData`'s generics
+
+Tracing through the `@remix-run/react` source code (v1.6.4), you'll find that `useLoaderData` returns an `any` type that is implicitly type cast to whatever type gets passed into the `useLoaderData` generic:
+
+```ts
+// https://github.com/remix-run/remix/blob/v1.6.4/packages/remix-react/components.tsx#L1370
+export function useLoaderData<T = AppData>(): T {
+  return useRemixRouteContext().data; //
+}
+
+// https://github.com/remix-run/remix/blob/v1.6.4/packages/remix-react/components.tsx#L73
+function useRemixRouteContext(): RemixRouteContextType {
+  /* ... */
+}
+
+// https://github.com/remix-run/remix/blob/v1.6.4/packages/remix-react/components.tsx#L56
+interface RemixRouteContextType {
+  data: AppData;
+  id: string;
+}
+
+// https://github.com/remix-run/remix/blob/v1.6.4/packages/remix-react/data.ts#L4
+export type AppData = any;
+```
+
+Boiling this down, the code looks like:
+
+```ts
+let data: any;
+
+// somewhere else, `loader` gets called an sets `data` to some value
+
+function useLoaderData<T>(): T {
+  return data; // <-- Typescript casts this `any` to `T`
+}
+```
+
+`useLoaderData` isn't basing its return type on how `data` was set (i.e. the return value of `loader`) nor is it validating the data.
+It's just blindly casting `data` to whatever the user passed in for the generic `T`.
+
+### Issues with current approach
+
+The developer experience is subpar.
+Users are required to write redundant code for the data types that could have been inferred from the arguments to `json`.
+Changes to the data shape require changing _both_ the declared `type` or `interface` as well as the argument to `json`.
+
+Additionally, the current approach encourages users to pass the same type to `json` with the `loader` and to `useLoaderData`, but **this is a footgun**!
+`json` can accept data types like `Date` that are JSON serializable, but `useLoaderData` will return the _serialized_ type:
+
+```ts
+type MyLoaderData = {
+  birthday: Date;
+};
+
+export const loader: LoaderFunction = () => {
+  return json<MyLoaderData>({ birthday: new Date("February 15, 1992") });
+};
+
+export default function Route() {
+  const { birthday } = useLoaderData<MyLoaderData>();
+  // ^ `useLoaderData` tricks Typescript into thinking this is a `Date`, when in fact its a `string`!
+}
+```
+
+Again, the same goes for `useActionData`.
+
+### Solution criteria
+
+- Return type of `useLoaderData` and `useActionData` should somehow be inferred from `loader` and `action`, not blindly type cast
+- Return type of `loader` and `action` should be inferred
+  - Necessarily, return type of `json` should be inferred from its input
+- No module side-effects (so higher-order functions like `makeLoader` is definitely a no).
+- `json` should allow everything that `JSON.stringify` allows.
+- `json` should allow only what `JSON.stringify` allows.
+- `useLoaderData` should not return anything that `JSON.parse` can't return.
+
+### Key insight: `loader` and `action` are an _implicit_ inputs
+
+While there's been interest in inferring the types for `useLoaderData` based on `loader`, there was [hesitance to use a Typescript generic to do so](https://github.com/remix-run/remix/pull/3276#issuecomment-1164764821).
+Typescript generics are apt for specifying or inferring types for _inputs_, not for blindly type casting output types.
+
+A key factor in the decision was identifying that `loader` and `action` are _implicit_ inputs of `useLoaderData` and `useActionData`.
+
+In other words, if `loader` and `useLoaderData` were guaranteed to run in the same process (and not cross the network), then we could write `useLoaderData(loader)`, specifying `loader` as an explicit input for `useLoaderData`.
+
+```ts
+// _conceptually_ `loader` is an input for `useLoaderData`
+function useLoaderData<Loader extends LoaderFunction>(loader: Loader) {
+  /*...*/
+}
+```
+
+Though `loader` and `useLoaderData` exist together in the same file at development-time, `loader` does not exist at runtime in the browser.
+Without the `loader` argument to infer types from, `useLoaderData` needs a way to learn about `loader`'s type at compile-time.
+
+Additionally, `loader` and `useLoaderData` are both managed by Remix across the network.
+While its true that Remix doesn't "own" the network in the strictest sense, having `useLoaderData` return data that does not correspond to its `loader` is an exceedingly rare edge-case.
+
+Same goes for `useActionData`.
+
+---
+
+A similar case is how [Prisma](https://www.prisma.io/) infers types from database schemas available at runtime, even though there are (exceedingly rare) edge-cases where that database schema _could_ be mutated after compile-time but before run-time.
+
+## Decision
+
+Explicitly provide type of the implicit `loader` input for `useLoaderData` and then infer the return type for `useLoaderData`.
+Do the same for `action` and `useActionData`.
+
+```ts
+export const loader = async (args: LoaderArgs) => {
+  // ...
+  return json(/*...*/);
+};
+
+export default function Route() {
+  const data = useLoaderData<typeof loader>();
+  // ...
+}
+```
+
+Additionally, the inferred return type for `useLoaderData` will only include serializable (JSON) types.
+
+### Return `unknown` when generic is omitted
+
+Omitting the generic for `useLoaderData` or `useActionData` results in `any` being returned.
+This hides potential type errors from the user.
+Instead, we'll change the return type to `unknown`.
+
+```ts
+type MyLoaderData = {
+  /*...*/
+};
+
+export default function Route() {
+  const data = useLoaderData();
+  // ^? unknown
+}
+```
+
+Note: Since this would be a breaking change, changing the return type to `unknown` will be slated for v2.
+
+### Deprecate non-inferred types via generics
+
+Passing in a non-inferred type for `useLoaderData` is hiding an unsafe type cast.
+Using the `useLoaderData` in this way will be deprecated in favor of an explicit type cast that clearly communicates the assumptions being made:
+
+```ts
+type MyLoaderData = {
+  /*...*/
+};
+
+export default function Route() {
+  const dataGeneric = useLoaderData<MyLoaderData>(); // <-- will be deprecated
+  const dataCast = useLoaderData() as MyLoaderData; // <- use this instead
+}
+```
+
+## Consequences
+
+- Users can continue to provide non-inferred types by type casting the result of `useLoaderData` or `useActionData`
+- Users can opt-in to inferred types by using `typeof loader` or `typeof action` at the generic for `useLoaderData` or `useActionData`.
+- Return types for `loader` and `action` will be the sources-of-truth for the types inferred for `useLoaderData` and `useActionData`.
+- Users do not need to write redundant code to align types across the network
+- Return type of `useLoaderData` and `useActionData` will correspond to the JSON _serialized_ types from `json` calls in `loader` and `action`, eliminating a class of errors.
+- `LoaderFunction` and `ActionFunction` should not be used when opting into type inference as they override the inferred return types.[^1]
+
+🚨 Users who opt-in to inferred types **MUST** return a `TypedResponse` from `json` and **MUST NOT** return a bare object:
+
+```ts
+const loader = () => {
+  // NO
+  return { hello: "world" };
+
+  // YES
+  return json({ hello: "world" });
+};
+```
+
+[^1]: The proposed `satisfies` operator for Typescript would let `LoaderFunction` and `ActionFunction` enforce function types while preserving the narrower inferred return type: https://github.com/microsoft/TypeScript/issues/47920
diff --git a/decisions/0004-streaming-apis.md b/decisions/0004-streaming-apis.md
new file mode 100644
index 0000000000..5677a48e36
--- /dev/null
+++ b/decisions/0004-streaming-apis.md
@@ -0,0 +1,193 @@
+---
+title: Remix (and React Router) Streaming APIs
+---
+
+# Title
+
+Date: 2022-07-27
+
+Status: accepted
+
+## Context
+
+Remix aims to provide first-class support for React 18's streaming capabilities. Throughout the development process we went through many iterations and naming schemes around the APIs we plan to build into Remix to support streaming, so this document aims to lay out the final names we chose and the reasons behind it.
+
+It's also worth nothing that even in a single-page-application without SSR-streaming, the same concepts still apply so these decisions were made with React Router 6.4.0 in mind as well - which will support the same Data APIs from Remix.
+
+## Decision
+
+Streaming in Remix can be thought of as having 3 touch points with corresponding APIs:
+
+1. _Initiating_ a streamed response in your `loader` can be done by returning a `defer(object)` call from your `loader` in which some of the keys on `object` are `Promise` instances
+2. _Accessing_ a streamed response from `useLoaderData`
+   1. No new APIs here - when you return a `defer()` response from your loader, you'll get `Promise` values inside your `useLoaderData` object 👌
+3. _Rendering_ a streamed value (with fallback and error handling) in your component
+   1. You can render a `Promise` from `useLoaderData()` with the `<Await resolve={data.promise}>` component
+   2. `<Await>` accepts an `errorElement` prop to handle error UI
+   3. `<Await>` should be wrapped with a `<React.Suspense>` component to handle your loading UI
+
+## Details
+
+In the spirit of `#useThePlatform` we've chosen to leverage the `Promise` API to represent these "eventually available" values. When Remix receives a `defer()` response back from a `loader`, it needs to serialize that `Promise` over the network to the client application (prompting Jacob to coin the phrase [_"promise teleportation over the network"_][promise teleportation] 🔥).
+
+### Initiating
+
+In order to initiate a streamed response in your `loader`, you can use the `defer()` utility which accepts a JSON object with `Promise` values from your `loader`.
+
+```tsx
+export async function loader() {
+  return defer({
+    // Await this, don't stream
+    critical: await fetchCriticalData(),
+    // Don't await this - stream it!
+    lazy: fetchLazyData(),
+  });
+}
+```
+
+By not using `await` on `fetchLazyData()` Remix knows that this value is not ready yet _but eventually will be_ and therefore Remix will leverage a streamed HTTP response allowing it to send up the resolved/rejected value when available. Essentially serializing/teleporting that Promise over the network via a streamed HTTP response.
+
+Just like `json()`, the `defer()` will accept a second optional `responseInit` param that lets you customize the resulting `Response` (i.e., in case you need to set custom headers).
+
+The name `defer` was settled on as a corollary to `<script defer>` which essentially tells the browser to _"fetch this script now but don't delay document parsing"_. In a similar vein, with `defer()` we're telling Remix to _"fetch this data now but don't delay the HTTP response"_.
+
+We decided _not_ to support naked objects due to the ambiguity that would be introduced:
+
+```tsx
+// NOT VALID CODE - This is just an example of the ambiguity that would have
+// been introduced had we chosen to support naked objects :)
+
+// This would NOT be streamed
+function exampleLoader1() {
+  return Promise.resolve(5);
+}
+
+// This WOULD be streamed
+function exampleLoader2() {
+  return {
+    value: Promise.resolve(5),
+  };
+}
+
+// This would NOT be streamed
+function exampleLoader3() {
+  return {
+    value: {
+      nested: Promise.resolve(5),
+    },
+  };
+}
+```
+
+<details>
+  <summary>Other considered API names:</summary>
+  <br/>
+  <ul>
+    <li><code>deferred()</code> - This is just a bit of a weird word that doesn't have much pre-existing semantic meaning. Is this the <code>jQuery.Deferred</code> thing from back in the day? Remix in general wants to avoid needlessly introducing net-new language to an already convoluted landscape!</li>
+    <li><code>stream()</code> - We also thought <code>stream</code> might be a good name since that's what the call is telling Remix to do - stream the responses down to the browser. But - this is also potentially misleading because stream is ambiguous in ths case. Developers may mistakenly think that this gives them back a <code>Stream</code> instance and they can arbitrarily send multiple chunks of data down to the browser over time. This is not how the current API works - but also seems like a really interesting idea for Remix to consider in the future, so we wanted to keep the <code>stream()</code> name available for future use cases.</li>
+  </ul>
+</details>
+
+### Accessing
+
+No new APIs are needed for the "Accessing" stage 🎉. Since we've "teleported" these promises over the network, you can access them in your components just as you would with any other data returned from your loader. This value will always be a `Promise`, even after it's been settled.
+
+```tsx
+function Component() {
+  const data = useLoaderData();
+  // data.critical is a resolved value
+  // data.lazy is a Promise
+}
+```
+
+### Rendering
+
+In order to render your `Promise` values from `useLoaderData()`, Remix provides a new `<Await>` component which handles rendering the resolved value, or propagating the rejected value through an `errorElement` or further upwards to the Route-level error boundaries. In order to access the resolved or rejected values, there are two new hooks that only work in the context of an `<Await>` component - `useAsyncValue()` and `useAsyncError()`.
+
+This examples shows the full set of render-time APIs:
+
+```tsx
+function Component() {
+  const data = useLoaderData(); // data.lazy is a Promise
+
+  return (
+    <React.Suspense fallback={<p>Loading...</p>}>
+      <Await resolve={data.lazy} errorElement={<MyError />}>
+        <MyData />
+      </Await>
+    </React.Suspense>
+  );
+}
+
+function MyData() {
+  const value = useAsyncValue(); // Get the resolved value
+  return <p>Resolved: {value}</p>;
+}
+
+function MyError() {
+  const error = useAsyncError(); // Get the rejected value
+  return <p>Error: {error.message}</p>;
+}
+```
+
+Note that `useAsyncValue` and `useAsyncError` only work in the context of an `<Await>` component.
+
+The `<Await>` name comes from the fact that for these lazily-rendered promises, we're not `await`-ing the promise in our loader, so instead we need to `<Await>` the promise in our render function and provide a fallback UI. The `resolve` prop is intended to mimic how you'd await a resolved value in plain Javascript:
+
+```tsx
+// This JSX:
+<Await resolve={promiseOrValue} />;
+
+// Aims to resemble this Javascript:
+const value = await Promise.resolve(promiseOrValue);
+```
+
+Just like `Promise.resolve` can accept a promise or a value, `<Await resolve>` can also accept a promise or a value. This is really useful in case you want to AB test `defer()` responses in the loader - you don't need to change the UI code to render the data.
+
+```tsx
+export async function loader({ request }: LoaderArgs) {
+  const shouldAwait = isUserInTestGroup(request);
+  return {
+    maybeLazy: shouldAwait ? await fetchData() : fetchData(),
+  };
+}
+
+function Component() {
+  const data = useLoaderData();
+
+  // No code forks even if data.maybeLazy is not a Promise!
+  return (
+    <React.Suspense fallback={<p>Loading...</p>}>
+      <Await resolve={data.maybeLazy} errorElement={<MyError />}>
+        <MyData />
+      </Await>
+    </React.Suspense>
+  );
+}
+```
+
+**Additional Notes on `<Await>`**
+
+If you prefer the render props pattern, you can bypass `useAsyncValue()` and just grab the value directly:
+
+```tsx
+<Await resolve={data.lazy}>{(value) => <p>Resolved: {value}</p>}</Await>
+```
+
+If you do not provide an `errorElement`, then promise rejections will bubble up to the nearest Route-level error boundary and be accessible via `useRouteError()`.
+
+<details>
+  <summary>Other considered API names:</summary>
+  <br>
+  <p>We originally implemented this as a <code>&lt;Deferred value={promise} fallback={&lt;Loader /&gt;} errorElement={&lt;MyError/&gt;} /></code>, but eventually we chose to remove the built-in <code>&lt;Suspense&gt;</code> boundary for better composability and eventual use with <code>&lt;SuspenseList&gt;</code>.  Once that was removed, and we were only using a <code>Promise</code> it made sense to move to a generic <code>&lt;Await&gt;</code> component that could be used with <em>any</em> promise, not just those coming from <code>defer()</code> in a <code>loader</code></p>
+
+  <p>We also considered various alternatives for the hook names - most notably `useResolvedValue`/`useRejectedValue`.  However, these were a bit too tightly coupled to the `Promise` nomenclature.  Remember, `Await` supports non-Promise values as well as render-errors, so it would be confusing if `useResolvedValue` was handing you a non-Promise value, or if `useRejectedValue` was handing you a render error from a resolved `Promise`.  `useAsyncValue`/`useAsyncError` better encompasses those scenarios as well.</p>
+</details>
+
+## React Router Notes
+
+With the presence of the `<Await>` component in React Router and because the Promise's don't have to be serialized over the network - you can _technically_ just return raw Promise values on a naked object from your loader. However, this is strongly discouraged because the router will be unaware of these promises and thus won't be able to cancel them if the user navigates away prior to the promise settling.
+
+By forcing users to call the `defer()` utility, we ensure that the router is able to track the in-flight promises and properly cancel them. It also allows us to handle synchronous rendering of promises that resolve prior to other critical data. Without the `defer()` utility these raw Promises would need to be thrown by the `<Await>` component to the `<Suspense>` boundary a single time to unwrap the value, resulting in a UI flicker.
+
+[promise teleportation]: https://twitter.com/ebey_jacob/status/1548817107546095616
diff --git a/decisions/0005-remixing-react-router.md b/decisions/0005-remixing-react-router.md
new file mode 100644
index 0000000000..9b24896a86
--- /dev/null
+++ b/decisions/0005-remixing-react-router.md
@@ -0,0 +1,309 @@
+# Remixing React Router
+
+Date: 2022-07-29
+
+Status: accepted
+
+- [Remixing React Router](#remixing-react-router)
+  - [Context](#context)
+  - [Decisions](#decisions)
+    - [Move the bulk of logic to a framework-agnostic router](#move-the-bulk-of-logic-to-a-framework-agnostic-router)
+    - [Inline the `history` library into the router](#inline-the-history-library-into-the-router)
+    - [`fetcher.load()` participates in revalidations](#fetcherload-participates-in-revalidations)
+    - [`useTransition` renamed to `useNavigation`](#usetransition-renamed-to-usenavigation)
+    - [Navigations/Fetchers state structure changes](#navigationsfetchers-state-structure-changes)
+    - [`<Form method="get">` is no longer a "submission"](#form-methodget-is-no-longer-a-submission)
+    - [Form automatic replace behavior](#form-automatic-replace-behavior)
+    - [`unstable_shouldReload` stabilized as `shouldRevalidate`](#unstable_shouldreload-stabilized-as-shouldrevalidate)
+    - [`<ScrollRestoration getKey>` prop](#scrollrestoration-getkey-prop)
+    - [`<Link preventScrollReset>` prop](#link-preventscrollreset-prop)
+    - [`useRevalidator()` hook](#userevalidator-hook)
+    - [No distinction between Error and Catch boundaries](#no-distinction-between-error-and-catch-boundaries)
+    - [`Request.signal` instead of `signal` param](#requestsignal-instead-of-signal-param)
+    - [React-Router API surface](#react-router-api-surface)
+
+## Context
+
+In [Remixing React Router][remixing router], Ryan gives an overview of the work we started out to do in bringing the data APIs from Remix (loaders, actions, fetchers) over to `react-router`. We made _many_ decisions along the way that we'll document here. In some cases we decided to proceed with behavior that is different from that of Remix today, or add net-new behavior that does not currently exist in Remix. We'll identify those cases as necessary and provide rationale for the divergence and how we plan to support backwards compatibility.
+
+## Decisions
+
+### Move the bulk of logic to a framework-agnostic router
+
+Thankfully this decision was sort of already made by Ryan. Maybe a surprise to some, maybe not, the current transition manager doesn't import or reference `react` or `react-router` a single time. This is by design because the logic being handled has nothing to do with how to render the UI layer. It's all about "what route am I on?", "what route am I going to?", "how do I load data for the next route?", "how do I interrupt ongoing navigations?" etc. None of these decisions actually _care_ about how the route and its data will eventually be rendered. Instead, the router simply needs to know whether given routes _have_ components and/or error boundaries - but it doesn't need to know about them or how to render them.
+
+This is a huge advantage since it's a strict requirement in order to eventually support UI libraries other than React (namely Preact and Vue). So in the end, we have a `@remix-run/router` package with _zero_ dependencies 🔥.
+
+### Inline the `history` library into the router
+
+`react-router@6.3` currently relies on the `history@5` package. When we first started the work, we were intending to bring `history` into the `react-router` repo and create `history@6` and it would still be a standalone package and a dependency of `@remix-run/router`. However, 3 things pushed us in a different direction and caused us to just make history a single file inside of the router, and treat it more as an implementation detail.
+
+**1. History is an implementation detail in a data-aware landscape**
+
+Now that the router is data-aware, it has to manage _both_ route data loading/mutations and the URL (or in-memory location state but for simplicity let's just talk in terms of browser-routers here). In `react-router@6.3`/`history@5` the router was purely _reactive_. It listened for `history` changes and rendered the proper UI. So if a user clicked a link, it updated `history` _and then_ informed the router "hey you should render this new location".
+
+This is no longer the case in a data-aware landscape. Now, when a user clicks a link, we need to first tell the router "hey the user _intends_ to go to this location." In response to that the router can initiate some data fetches but during these fetches we're still on the old page! The user is still looking at the old content, and the URL should reflect that. This fits with the "browser emulator" concept as well. If you had a non-JS landscape and a user clicked a link from `/a -> /b` and the server took 5 seconds to send back a response for `/b` - during that time the browser URL bar shows the URL and title for `/a` and a little spinner in the tab. This is exactly how we built the router, it first loads data, then it updates state and tells history to update the URL.
+
+There's one caveat here when it comes to back/forward button usage. When the user navigates back/forward in the history stack we get a `popstate` event _but the URL has already been updated_. So the best we can do there is react to the new URL. This is _not_ what the browser would do in a non-JS world, but we really have no choice.
+
+All this being said - history is no longer a simple process of "update the URL then tell the router to re-render". History and routing are far more intertwined and behave slightly differently for PUSH/REPLACE than they do for POP navigations. For PUSH/REPLACE we go `router.navigate -> load data -> update state -> update history`, but for POP we `update history -> router.navigate -> load data -> update state`. So in PUSH, the router informs history. But in POP, history informs the router. These nuances made sense to keep the router as the public API and make history more of an internal implementation detail.
+
+**2. History is being superseded via the Navigation API**
+
+With the pending [Navigation API][navigation api] in the works, there's potentially a not-too-distant future where we aren't using `window.history` at all or in the same way, so by moving our own `history` abstraction to an implementation detail we keep ourselves better poised to adopt the Navigation API in a non-breaking manner.
+
+**3. Initial implementations required it**
+
+In the first implementations we actually didn't touch the internals of `BrowserRouter` and it's non-data-aware counterparts. And due to the changes we made in `history` to not notify listeners on PUSH/REPLACE wouldn't work. So for a very short period, we actually had both history v5 and this new internal history so we _couldn't_ publish it as history v6 since you can't have multiple dependent versions. Eventually, this went away as we added a `v5Compat` flag to the new history so it could behave like v5 used to when needed.
+
+### `fetcher.load()` participates in revalidations
+
+In Remix, if you have data on a page from a `fetcher.load()` and you submit a mutation - those fetchers don't revalidate so the data may now be stale if the mutation impacted it. We've changed this in `@remix-run/router` such that revalidation updates _all_ active loaded data including route loaders as well as active `fetcher.load()` calls. These can be opted out of using the normal `shouldRevalidate()` method
+
+**Backwards Compatibility**
+
+We categorize this as a bug fix since fetchers get stale in current Remix apps
+
+### `useTransition` renamed to `useNavigation`
+
+This was done for two reasons:
+
+- Avoid confusion with the [`useTransition`][react usetransition] hook in React 18
+- It's more semantically correct because a "navigation" is what you trigger as a result of `router.navigate()` or `useNavigate()`
+
+**Backwards Compatibility**
+
+We plan to export `useNavigation` in Remix and encourage folks to switch, but we will continue to include `useTransition` in a deprecated fashion
+
+### Navigations/Fetchers state structure changes
+
+**`useTransition().type` is removed**
+
+In Remix, the `useTransition` hook returned a Transition object which had a `state` property of `"idle" | "loading" | "submitting"`. It also had a `type` property which represented sort of "sub-states" such as `"normalLoad" | "actionReload" | "loaderRedirect"` etc. In React Router we chose to get rid of the `type` field for 2 reasons:
+
+1. In practice, we found that the _vast_ majority of the time all you needed to reference was the `state`
+2. For scenarios in which you really do need to distinguish, we are pretty sure that in all cases, you can deduce the `type` from `state`, current location (`useLocation`), next location (`useNavigation().location`), and submission info (`useNavigation().formData`).
+
+**`useTransition().submission` is flattened**
+
+Another area that changes is the `useTransition().submission` property was removed. We found that in practice folks never really needed the submission as a standalone thing, and instead always just cared about the `formMethod` or `formData`. So we flattened them onto the navigation, so `useNavigation()` will return an object of the format:
+
+```
+{
+  state: "idle" | "loading" | "submitting";
+  location: Location;
+  formMethod?: FormMethod;
+  formAction?: string;
+  formEncType?: FormEncType;
+  formData?: FormData;
+}
+```
+
+**Backwards Compatibility**
+
+We plan to remain backwards compatible here in Remix. Very likely we'll expose the `useNavigation` hook and encourage users to move to that. And then `useTransition` will remain in a deprecated state and it will call `useNavigation` and then backfill the `type` and `submission` properties.
+
+### `<Form method="get">` is no longer a "submission"
+
+Functionally, these two bits of code are identical, with the only difference being that in the `<form>` case you let the user determine the query value.
+
+```html
+<a href="/search?query=matt">Search</a>
+
+<form action="/search">
+  <input name="query" value="matt" />
+  <button type="submit">Search</button>
+</form>
+```
+
+But, in Remix we were considering the latter a "submission" such that `useTransition().state === "submitting"`. In order to ensure our "navigations" reflect the browser behavior, we have changed this in the router such that GET Form submissions result in `useNavigation().state === "loading"`.
+
+**Backwards Compatibility**
+
+This will be handled in the deprecated `useTransition` hook along with the backfill of `type` and `submission` properties
+
+### Form automatic replace behavior
+
+When performing POST navigations, you don't want to end up with a duplicate entry in the history stack which makes back-button routing weird when going through the same page twice. This is further complicated in browsers that hang onto the submission info and thus have to prompt you to warn you of re-submitting your data. We'll look at a few examples to demonstrate, but the intention is that the default behavior of the router should ensure that you can't get yourself into this double-history-entry situation when using `<Form method="post">` submission navigations.
+
+Normal POST submissions that do not redirect will use a `REPLACE`:
+
+- User is on `/` (history stack is `[/]`)
+- Navigates to `/login` (history stack is `[/, /login]`)
+- Fills out and submits the `<Form method="post">`
+- Action does not redirect
+  - At this point, if the action returns a non-redirect and we were to PUSH the navigation we'd end up with a history stack of `[/, /login, /login]` and the user would be in a scenario where it would take them 2 back buttons to get "through" the login page from a subsequent route.
+  - To avoid this, when a POST submission does not return a redirect, the router will REPLACE in the history stack, leaving us at `[/, /login]` and avoiding the duplicate history entry
+
+Normal POST submissions that _do_ redirect will use `PUSH` for the redirect:
+
+- User is on `/` (history stack is `[/]`)
+- Navigates to `/login` (history stack is `[/, /login]`)
+- Fills out and submits the `<Form method="post">`
+- Action redirects to `/private`
+  - If we treated this redirect as a REPLACE, we'd be replacing the _initial_ navigation to `/login` since we haven't yet touched history for the POST. This would leave the history stack as `[/, /private]` and we'd lose the fact that we were ever at the login page.
+  - Instead when an action redirects, we'll use a PUSH and in this case the history stack would become `[/, /login, /private]` and the user would be able to navigate back through the login page and to the home page
+
+Note: User's can still be explicit here and use `<Form method="post" replace={shouldReplace}>` and the router will respect the value passed to `replace`.
+
+### `unstable_shouldReload` stabilized as `shouldRevalidate`
+
+We stabilized the API for when a given route loader should re-run, and changed the name to align with the "revalidation" nomenclature and the `useRevalidator` hook. We also leave more control in the hands of the user here. In Remix there were some cases in which you _could not_ opt out of revalidation and if your method did run, you had full control and couldn't necessarily handle one edge case and then say "do what you otherwise would have done".
+
+Now, if you provide a `shouldRevalidate` method we will call it during all revalidations and provide you a `defaultShouldRevalidate` boolean value. This allows you to opt out of any revalidation, and also code your own logic to fallback on our default choice:
+
+```tsx
+function shouldRevalidate({ defaultShouldRevalidate }) {
+  // Don't revalidate for this case
+  if (someEdgeCase()) {
+    return false;
+  }
+
+  // Otherwise, do what we would have done by default
+  return defaultShouldRevalidate;
+}
+```
+
+### `<ScrollRestoration getKey>` prop
+
+In Remix, the `<ScrollRestoration>` component made an assumption that we would always restore scroll position based on `location.key`. If the key was the same as a prior location we knew the scroll position for, then we knew you had been there before and we should restore. This works great for back/forward navigations but it's a bit overly restrictive. You cannot choose to restore scroll based on anything other than `key`.
+
+Twitter has a great implementation of this as you click around in their left nav bar - your tweet feed is always at the same place when you click back to it - even though it's a _new_ location in the history stack. This is because they're restoring by pathname here instead of `location.key`. Or maybe you want to maintain scroll position for all routes under a given pathname and you thus want to use a portion of the pathname as the scroll restoration key.
+
+In React Router we now accept an optional `<ScrollRestoration getKey>` prop where you provide a function that returns the key to use for scroll restoration:
+
+```ts
+function getKey(location: Location, matches: DataRouteMatch[]) {
+  // Restore by pathname on /tweets
+  if (location.pathname === "/tweets") {
+    return location.pathname;
+  }
+  // Otherwise use the key
+  return location.key;
+}
+```
+
+**Backwards Compatibility**
+
+We're ok here since the new prop is optional and defaults to using `location.key`
+
+### `<Link preventScrollReset>` prop
+
+In addition to `<ScrollRestoration>` handling "restoring" scroll position on previously visited routes. It also handles "resetting" scroll position back to the top on _new_ routes. This is not always desirable if you're clicking around inside a tabbed view or something, so we've introduced a new `<Link preventScrollReset>` prop that lets you disable the scroll reset behavior _for a given navigation_. Note that this "resetting" logic happens if and only if we cannot restore scroll to a previously known location for that scroll restoration key.
+
+### `useRevalidator()` hook
+
+This has been a long time coming - see https://github.com/remix-run/remix/discussions/1996 🙂
+
+### No distinction between Error and Catch boundaries
+
+The differentiation between error and catch proved to be a bit vague over time and a source of confusion for developers. We chose to go with just a single `errorElement` in the router for simplicity. If you throw anything, it ends up in the error boundary (available via `useRouteError`) and propagates accordingly. With this approach we leave the control in the developers hands and it's easy to maintain a similar split if desired:
+
+```tsx
+function NewErrorBoundary() {
+  const error = useRouteError();
+
+  if (error instanceof Response) {
+    return <MyOldCatchBoudnary error={error} />;
+  } else {
+    return <MyOldErrorBoundary error={error} />;
+  }
+}
+```
+
+**Backwards Compatibility**
+
+We have a few options here. In all cases, Remix v1 will provide an internal `errorElement` implementation that will need to do some forking to maintain backwards compatibility.
+
+1. We could introduce a new `ErrorComponent` in Remix v1 and deprecate `ErrorBoundary`/`CatchBoundary` (and eventually drop them in v2)
+   1. Chose this over `ErrorElement` since the thing being exported has not been through `React.createElement`
+2. We could maintain the same behavior of `ErrorBoundary`/`CatchBoundary` in v1 and plan to drop` CatchBoundary` in v2 and send everything to `ErrorBoundary`
+3. Keep the name `ErrorBoundary` and introduce a flag in `remix.config.js` to opt into the new behavior where all errors go to the `ErrorBoundary` and Remix stops separating them out to the catch boundary
+
+The current favorite is likely option 3, which keeps the most semantic naming for Remix v2 while allowing users to start migrating to the new behavior in v1, thus easing their eventual upgrade to Remix v2.
+
+### `Request.signal` instead of `signal` param
+
+We dropped the `signal` parameter to loaders and actions because an incoming `Request` already has its own signal!
+
+**Backwards Compatibility**
+
+We'll need to re-expose the `request.signal` as a standalone `signal` in Remix
+
+### React-Router API surface
+
+Initially, we chose to align closely with the existing `react-router` APIs and introduced a `<DataBrowserRouter>` component (and it's memory/hash siblings) that would internally read the routes and create a router singleton upon first render. But as time went on we noticed some rough non-obvious foot guns with this approach, so we changed it up in [#9227][remove-singleton-pr]. Here's a few of the headaches it was causing:
+
+- Unit tests were a pain because you need to find a way to reset the singleton in-between tests
+  - We used a `_resetModuleScope` method for our tests
+  - ...but this wasn't't exposed to users who may want to do their own tests around our router
+- The JSX children `<Route>` objects caused non-intuitive behavior based on idiomatic react expectations
+  - Conditional runtime `<Route>`'s wouldn't get picked up
+  - Adding new `<Route>`'s during local dev wouldn't get picked up during HMR
+  - Using external state in your elements doesn't work as one might expect (see [#9225][singleton-state-issue])
+
+Instead, we lifted the singleton out into user-land, so that they create the router singleton and manage it outside the react tree - which is what react 18 is encouraging with `useSyncExternalStore` anyways! This also means that since users create the router - there's no longer any difference in the rendering aspect for memory/browser/hash routers (which only impacts router/history creation) - so we got rid of those and trimmed to a simple `RouterProvider`:
+
+```tsx
+// Before
+function OldApp() {
+  return (
+    <DataBrowserRouter>
+      <Route path="/" element={<Layout />}>
+        <Route index element={<Home />} />
+      </Route>
+    </DataBrowserRouter>
+  );
+}
+```
+
+```tsx
+//After
+const router = createBrowserRouter([
+  {
+    path: "/",
+    element: <Layout />,
+    children: [
+      {
+        index: true,
+        element: <Home />,
+      },
+    ],
+  },
+]);
+
+function NewApp() {
+  return <RouterProvider router={router} />;
+}
+```
+
+If folks still prefer the JSX notation, they can leverage `createRoutesFromElements` (aliased from `createRoutesFromChildren` since they are not "children" in this usage):
+
+```tsx
+const routes = createRoutesFromElements(
+  <Route path="/" element={<Layout />}>
+    <Route index element={<Home />} />
+  </Route>
+);
+const router = createBrowserRouter(routes);
+
+function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+And now they can also hook into HMR correctly for router disposal:
+
+```
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => router.dispose());
+}
+```
+
+And finally since `<RouterProvider>` accepts a router, it makes unit testing easer since you can create a fresh router with each test.
+
+[remixing router]: https://remix.run/blog/remixing-react-router
+[navigation api]: https://developer.chrome.com/docs/web-platform/navigation-api/
+[react usetransition]: https://reactjs.org/docs/hooks-reference.html#usetransition
+[remove-singleton-pr]: https://github.com/remix-run/react-router/pull/9227
+[singleton-state-issue]: https://github.com/remix-run/react-router/pull/9225
diff --git a/decisions/0006-linear-workflow.md b/decisions/0006-linear-workflow.md
new file mode 100644
index 0000000000..6f47d1d6e9
--- /dev/null
+++ b/decisions/0006-linear-workflow.md
@@ -0,0 +1,86 @@
+# Linear Workflow
+
+Date: 2022-09-06
+
+Status: accepted
+
+## Context
+
+The Remix development team uses Linear internally to manage and prioritize ongoing development of Remix and React-Router. In order to keep this process flowing smoothly, we document here the set of established workflows within Linear, so developers have a documented process to refer to if questions should arise.
+
+## Linear Terms
+
+This document will use many of the following Linear terms:
+
+- **Issue** - A ticket/task in the Linear system that describes a unit of work to be completed
+- **Cycle** - A group of issues aimed to be completed within a given 1-week period (similar to a "sprint" in other Agile workflows)
+- **Project** - A group of issues that comprise a larger scope of work (for example, a new feature)
+  - Projects will almost always span multiple Cycles.
+- **Status** - The state of a given Issue (Todo, In Progress, Done, etc.)
+- **Assignee** - The person the Issue is currently assigned to - this indicates who is expected to take the next action to move the Issue forward
+- **Label** - Linear Issues can be assigned one or more Labels for filtering/searching
+
+## Decision
+
+### Status Definitions
+
+The Linear workflow is governed by the **Status** field, which has the following options:
+
+- **Triage** - Issue is not yet reviewed and we have no idea if we'll actually do this work
+- **Backlog** - Issue has been accepted as something we would like to do, but is not currently planned
+- **Todo** - Issue has been planned for a given Cycle of work
+- **In Progress** - Issue is actively being worked on in the active Cycle
+- **In Review** - Issue is completed and in a PR receiving feedback
+- **Needs Feedback** - Developer is blocked and needs feedback from someone else before they can be unblocked
+- **Done** - Issue has been completed and merged (note this does not mean released)
+- **Canceled** - Issue is not going to be done
+
+### General Workflow
+
+Generally, the Linear workflow is as follows:
+
+```mermaid
+graph TD
+    A(Github/Discord/???) -->|intake| Triage
+    Triage -->|accepted| Backlog
+    Triage -->|rejected| Canceled
+    Backlog -->|planned| Todo
+    Todo -->|picked up| InProgress(In Progress)
+    InProgress -->|PR| InReview(In Review)
+    InProgress -->|stopped| Todo
+    InProgress -->|blocked| NeedsFeedback(Needs Feedback)
+    NeedsFeedback -->|unblocked| InProgress
+    InReview -->|larger changes| InProgress
+    InReview -->|small comments| InReview
+    InReview -->|merged| Done
+```
+
+In more detail, the following is the _standard_ flow of a Linear Issue:
+
+1. When an idea or bug fix is identified through a Github Discussion/Issue/PR, we will create a Linear Issue in the **Triage** Status to track the task
+   1. This should contain an appropriate title and a link to the original idea in github
+2. The issue will be reviewed by the team (with final approval on larger changes and new APIs coming from Michael/Ryan)
+   1. If we want to move forward with the Issue, it gets moved to the **Backlog** Status
+   2. If we do not want to move forward with the Issue, it get moved to the **Canceled** Status, with appropriate reasoning provided in the Linear Issue and the original Github source.
+3. Periodically, Issues in the **Backlog** Status will be planned into a given cycle, and moved to the **Todo** Status
+4. During the active Cycle, a developer will pick up a ticket to start work and will move it into the **In Progress** Status
+5. Once the work is completed and a PR is opened, the developer will move the Issue to the **In Review** Status and assign it to the person who should perform the review
+6. If feedback is needed, comments can be left on the PR and the ticket can switch between assignees while remaining in the **In Review** status
+   1. Only for larger-scale changes should an Issue be moved back to **In Progress**
+7. Once merged, the Issue can be moved to the **Done** Status
+
+As always, this is not an absolute workflow and there will be exceptions. Here's a few examples:
+
+- If an issue opened on Github is a small bugfix, it can bypass the **Triage** status and go straight to the **Backlog** status. Or potentially even right into **Todo** if a developer has capacity to pick up the bug in the active (or upcoming) Cycle.
+- If a developer is blocked on moving forward with an Issue, it can be moved to the **Needs Feedback** Status and assigned to the person who can unblock the Issue
+- Sometimes an issue will be abandoned well after it was accepted and moved into the **Backlog** Status, and in these cases an Issue can always be assigned to **Canceled**
+
+### Ongoing Processes
+
+- Any idea/bug coming in via Github or Discord (or elsewhere) can be put into an Issue in the **Triage** status for review
+- Michael and Ryan should review the **Triage** Issues on a regular (weekly?) basis and move tickets to **Backlog** or **Canceled**
+  - If tickets are accepted, they should be given appropriate Labels and/or Projects
+  - If tickets are rejected, we should provide the rationale in the Linear ticket and on the original source (i.e., github)
+- Michael/Ryan (and team?) will decide what to work on in a given Cycle and move tickets from **Backlog** to **Todo** and assign a proper Cycle
+- All team members should review any tickets assigned to them on a regular (daily?) basis and provide reviews/feedback as needed to keep tickets moving along
+- All team members should work from their **Todo** queue during active Cycles
diff --git a/decisions/0007-remix-on-react-router-6-4-0.md b/decisions/0007-remix-on-react-router-6-4-0.md
new file mode 100644
index 0000000000..7d925c4299
--- /dev/null
+++ b/decisions/0007-remix-on-react-router-6-4-0.md
@@ -0,0 +1,166 @@
+# Layering Remix on top of React Router 6.4
+
+Date: 2022-08-16
+
+Status: accepted
+
+## Context
+
+Now that we're almost done [Remixing React Router][remixing-react-router] and will be shipping `react-router@6.4.0` shortly, it's time for us to start thinking about how we can layer Remix on top of the latest React Router. This will allow us to delete a _bunch_ of code from Remix for handling the Data APIs. This document aims to discuss the changes we foresee making and some potential iterative implementation approaches to avoid a big-bang merge.
+
+From an iterative-release viewpoint, there's 4 separate "functional" aspects to consider here:
+
+1. Server data loading
+2. Server react component rendering
+3. Client hydration
+4. Client data loading
+
+(1) can be implemented and deployed in isolation. (2) and (3) need to happen together since the contexts/components need to match. And (4) comes for free since the loaders/actions will be included on the routes we create in (3).
+
+## Decision
+
+The high level approach is as follows
+
+1.  SSR data loading
+    1.  Update `handleResourceRequest` to use `createStaticHandler` behind a flag
+        1.  Aim to get unit and integration tests asserting both flows if possible
+    2.  Update `handleDataRequest` in the same manner
+    3.  Update `handleDocumentRequest` in the same manner
+        1.  Confirm unit and integration tests are all passing
+    4.  Write new `RemixContext` data into `EntryContext` and remove old flow
+2.  Deploy `@remix-run/server-runtime` changes once comfortable
+3.  Handle `@remix-run/react` in a short-lived feature branch
+    1.  server render without hydration (replace `EntryContext` with `RemixContext`)
+    2.  client-side hydration
+    3.  add backwards compatibility changes
+4.  Deploy `@remix-run/react` changes once comfortable
+
+## Details
+
+There are 2 main areas where we have to make changes:
+
+1. Handling server-side requests in `@remix-run/server-runtime` (mainly in the `server.ts` file)
+2. Handling client-side hydration + routing in `@remix-run/react` (mainly in the `components.ts`, `server.ts` and `browser.ts` files)
+
+Since these are separated by the network chasm, we can actually implement these independent of one another for smaller merges, iterative development, and easier rollbacks should something go wrong.
+
+### Do the server data-fetching migration first
+
+There's two primary reasons it makes sense to handle the server-side data-fetching logic first:
+
+1. It's a smaller surface area change since there's effectively only 1 new API to work with in `createStaticHandler`
+2. It's easier to implement in a feature-flagged manner since we're on the server and bundle size is not a concern
+
+We can do this on the server using the [strangler pattern][strangler-pattern] so that we can confirm the new approach is functionally equivalent to the old approach. Depending on how far we take it, we can assert this through unit tests, integration tests, as well as run-time feature flags if desired.
+
+For example, pseudo code for this might look like the following, where we enable via a flag during local development and potentially unit/integration tests. We can throw exceptions anytime the new static handler results in different SSR data. Once we're confident, we delete the current code and remove the flag conditional.
+
+```tsx
+// Runtime-agnostic flag to enable behavior, will always be committed as
+// `false` initially, and toggled to true during local dev
+const ENABLE_REMIX_ROUTER = false;
+
+async function handleDocumentRequest({ request }) {
+  const appState = {
+    trackBoundaries: true,
+    trackCatchBoundaries: true,
+    catchBoundaryRouteId: null,
+    renderBoundaryRouteId: null,
+    loaderBoundaryRouteId: null,
+    error: undefined,
+    catch: undefined,
+  };
+
+  // ... do all the current stuff
+
+  const serverHandoff = {
+    actionData,
+    appState: appState,
+    matches: entryMatches,
+    routeData,
+  };
+
+  const entryContext = {
+    ...serverHandoff,
+    manifest: build.assets,
+    routeModules,
+    serverHandoffString: createServerHandoffString(serverHandoff),
+  };
+
+  // If the flag is enabled, process the request again with the new static
+  // handler and confirm we get the same data on the other side
+  if (ENABLE_REMIX_ROUTER) {
+    const staticHandler = unstable_createStaticHandler(routes);
+    const context = await staticHandler.query(request);
+
+    // Note: == only used for brevity ;)
+    assert(entryContext.matches === context.matches);
+    assert(entryContext.routeData === context.loaderData);
+    assert(entryContext.actionData === context.actionData);
+
+    if (catchBoundaryRouteId) {
+      assert(appState.catch === context.errors[catchBoundaryRouteId]);
+    }
+
+    if (loaderBoundaryRouteId) {
+      assert(appState.error === context.errors[loaderBoundaryRouteId]);
+    }
+  }
+}
+```
+
+We can also split this into iterative approaches on the server too, and do `handleResourceRequest`, `handleDataRequest`, and `handleDocumentRequest` independently (either just implementation or implementation + release). Doing them in that order would also likely go from least to most complex.
+
+#### Notes
+
+- This can't use `process.env` since the code we're changing is runtime agnostic. We'll go with a local hardcoded variable in `server.ts` for now to avoid runtime-specific ENV variable concerns.
+  - Unit and integration tests may need to have their own copies of this variable as well to remain passing. For example, we have unit tests that assert that a loader is called once for a given route - but when this flag is enabled, that loader will be called twice so we can set up a conditional assertion based on the flag.
+- The `remixContext` sent through `entry.server.ts` will be altered in shape. We consider this an opaque API so not a breaking change.
+
+#### Implementation approach
+
+1. Use `createHierarchicalRoutes` to build RR `DataRouteObject` instances
+   1. See `createStaticHandlerDataRoutes` in the `brophdawg11/rrr` branch
+2. Create a static handler per-request using `unstable_createStaticHandler`
+3. `handleResourceRequest`
+   1. This one should be _really_ simple since it should just send back the raw `Response` from `queryRoute`
+4. `handleDataRequest`
+   1. This is only slightly more complicated than resource routes, as it needs to handle serializing errors and processing redirects into 204 Responses for the client
+5. `handleDocumentRequest`
+   1. This is the big one. It simplifies down pretty far, but has the biggest surface area where some things don't quite match up
+   2. We need to map query "errors" to Remix's definition of error/catch and bubble them upwards accordingly.
+      1. For example, in a URL like `/a/b/c`, if C exports a `CatchBoundary` but not an `ErrorBoundary`, then it'll be represented in the `DataRouteObject` with `hasErrorBoundary=true` since the `@remix-run/router` doesn't distinguish
+      2. If C's loader throws an error, the router will "catch" that at C's `errorElement`, but we then need to re-bubble that upwards to the nearest `ErrorBoundary`
+      3. See `differentiateCatchVersusErrorBoundaries` in the `brophdawg11/rrr` branch
+   3. New `RemixContext`
+      1. `manifest`, `routeModules`, `staticHandlerContext`, `serverHandoffString`
+      2. Create this alongside `EntryContext` assert the values match
+   4. If we catch an error during render, we'll have tracked the boundaries on `staticHandlerContext` and can use `getStaticContextFromError` to get a new context for the second pass (note the need to re-call `differentiateCatchVersusErrorBoundaries`)
+
+### Do the UI rendering layer second
+
+The rendering layer in `@remix-run/react` is a bit more of a whole-sale replacement and comes with backwards-compatibility concerns, so it makes sense to do second. However, we can still do this iteratively, we just can't deploy iteratively since the SSR and client HTML need to stay synced (and associated hooks need to read from the same contexts). First, we can focus on getting the SSR document rendered properly without `<Scripts/>`. Then second we'll add in client-side hydration.
+
+The main changes here include:
+
+- Removal of `RemixEntry` and it's context in favor of a new `RemixContext.Provider` wrapping `DataStaticRouter`/`DataBrowserRouter`
+  - All this context needs is the remix-specific aspects (`manifest`, `routeModules`)
+  - Everything else from the old RemixEntryContext is now in the router contexts (and `staticHandlerContext` during SSR)
+- Some aspects of `@remix-run/react`'s `components.tsx` file are now fully redundant and can be removed completely in favor of re-exporting from `react-router-dom`:
+  - `Form`, `useFormAction`, `useSubmit`, `useMatches`, `useFetchers`
+- Other aspects are largely redundant but need some Remix-specific things, so these will require some adjustments:
+  - `Link`, `useLoaderData`, `useActionData`, `useTransition`, `useFetcher`
+
+#### Backwards Compatibility Notes
+
+- `useLoaderData`/`useActionData` need to retain their generics, and are not currently generic in `react-router`
+- `useTransition` needs `submission` and `type` added
+  - `<Form method="get">` no longer goes into a "submitting" state in `react-router-dom`
+- `useFetcher` needs `type` added
+- `unstable_shouldReload` replaced by `shouldRevalidate`
+  - Can we use it if it's there but prefer `shouldRevalidate`?
+- Distinction between error and catch boundaries
+- `Request.signal` - continue to send separate `signal` param
+
+[remixing-react-router]: https://remix.run/blog/remixing-react-router
+[strangler-pattern]: https://martinfowler.com/bliki/StranglerFigApplication.html
diff --git a/decisions/0008-only-support-js-conversion-for-app-code.md b/decisions/0008-only-support-js-conversion-for-app-code.md
new file mode 100644
index 0000000000..677fce3755
--- /dev/null
+++ b/decisions/0008-only-support-js-conversion-for-app-code.md
@@ -0,0 +1,101 @@
+# Only support JS conversion for app code
+
+Date: 2023-01-20
+
+Status: accepted
+
+## Context
+
+Remix defaults to Typescript, but some users prefer to use Javascript.
+When creating a new Remix project via `npx create-remix` today, the CLI asks the user if they'd
+prefer to use Typescript or Javascript.
+
+```sh
+❯ npx create-remix@latest
+? Where would you like to create your app? ./my-remix-app
+? What type of app do you want to create? Just the basics
+? Where do you want to deploy? Choose Remix App Server if you're unsure; it's easy to change deployment targets. Remix App Server
+? TypeScript or JavaScript? (Use arrow keys)
+❯ TypeScript
+  JavaScript
+```
+
+Originally, this was implemented by having separate variants of a template for TS and JS.
+This worked, but duplicated huge portions of templates making those variants hard to maintain.
+To fix this, the decision was made to maintain _only_ the TS variant of each template.
+To provide JS-only Remix projects, the Remix CLI would copy the TS template and then dynamically
+convert all Typescript-related code to their Javascript equivalents.
+
+While converting the code in the Remix app directory (e.g. `app/`) is reliable, conversion of
+TS-related code outside of the `app/` directory are tricky and error-prone.
+
+### 1 Stale references to `.ts` files
+
+For example, both the [Indie][indie-stack] and [Blues][blues-stack] stacks have broken scripts when selecting `Javascript`,
+because they still reference `server.ts` and `seed.ts`.
+They also still reference TS-only tools like `ts-node` in their scripts.
+
+### 2.a MJS
+
+When transpiling code outside of the `app/` directory from TS to JS, the easiest thing to do is
+to convert to ESM-style `.mjs` since Remix app code already uses ESM.
+
+ESM-style JS requires one of the following:
+
+- a) Set `"type": "module"` in `package.json`
+- b) Use `.mjs` extension
+
+(a) immediately breaks Remix's builds since the settings in `package.json` apply to app code, not just code and
+scripts outside of the app directory.
+
+(b) seems more promising, but `.mjs` files require file extensions for import specifiers.
+Reliably changing relative imports without extensions to have the proper extensions is
+untractable since not all imports will be for `.js` files.
+
+```js
+// ./script.mjs (converted from ./script.js)
+import myHelper from "./my-helper";
+
+// Should this be converted to `./my-helper.mjs`?
+// Probably, but can we be sure?
+
+myHelper();
+```
+
+Maybe there's a way to do this, but the complexity cost seems high.
+
+### 2.b CJS
+
+If we don't use the `.mjs` extension, Node will default to treating scripts and code outside of the app directory
+as CJS.
+Since CJS doesn't support ESM-style `import`/`export`, we'd then need to convert all `import`s and `export`s to their
+equivalent `require`/`module.exports`.
+
+Important to remember that the converted code is meant to be read and edited by other developers, so its not acceptable
+to produce a bunch of boilerplate adapters for the imports and exports as would be typical in build output.
+
+Converting the imports and exports may be doable, but again, carries high complexity cost.
+
+## Decision
+
+Only support JS conversion for app code, not for scripts or code outside of the Remix app directory.
+
+## Consequences
+
+Users will have three options:
+
+1. Use a Typescript template
+2. Use a Typescript template with app directory converted to JS
+3. Use a dedicated Javascript template
+
+### Converting remaining TS to JS
+
+If you don't like the remaining TS from option (2) and cannot find a suitable template for option (3),
+you can still remove any remaining Typescript code manually:
+
+- Remove `tsconfig.json` or replace it with the equivalent `jsconfig.json`
+- Replace TS-only tools with their JS counterparts (e.g. `ts-node` -> `node`)
+- Change any remaining `.ts` files to `.mjs` and update imports and other references (like `package.json` scripts) to refer to the new filename
+
+[indie-stack]: https://github.com/remix-run/indie-stack
+[blues-stack]: https://github.com/remix-run/blues-stack
diff --git a/decisions/0009-do-not-rely-on-treeshaking-for-correctness.md b/decisions/0009-do-not-rely-on-treeshaking-for-correctness.md
new file mode 100644
index 0000000000..f007f258da
--- /dev/null
+++ b/decisions/0009-do-not-rely-on-treeshaking-for-correctness.md
@@ -0,0 +1,98 @@
+# Do not rely on treeshaking for correctness
+
+Date: 2024-01-02
+
+Status: accepted
+
+## Context
+
+Remix lets you write code that runs on both the server and the client.
+For example, it's common to have server and client code in the same route file.
+While blending server and client code is convenient, Remix needs to ensure that server-only code is never shipped to the client.
+This prevents secrets available to the server from leaking into client and also prevents the client from crashing due to code that expects a server environment.
+
+Server-only code comes in three forms:
+
+1. Server-only route exports like `loader`, `action`, `headers`, etc.
+2. Imports from `.server` directories or `.server` files.
+3. Imports from server-only packages like `node:fs`
+
+Remix previously relied on treeshaking to exclude server-only code.
+Specifically, Remix used [virtual modules for each route][virtual-modules] that re-exported client-safe exports from the route.
+For a brief stint, Remix instead used [AST transforms][ast-transforms] to remove server-only exports.
+In either case, Remix would remove server exports from routes and then let the bundler treeshake any unused code and dependencies from the client bundle.
+
+The main benefit is that server and client code can co-exist in the same module graph and even the same file
+and the treeshaking saves you from the tedium of explicitly marking or separating server-only code yourself.
+
+### Human error
+
+However, this is also the main drawback; "server-only" is implicit and must be inferred by thorough treeshaking.
+Even if treeshaking were perfect, this approach still leaves the door open to human error.
+If you or anyone on your team accidentally references server-only code from client code, the bundler will happily include that code in the client.
+You won't get any indication of this at build time, but only at runtime.
+Your app could crash when trying to execute code meant for the server, or worse, you could accidentally ship secrets to the client.
+
+### `.server` modules
+
+Instead of hoping such an accident never happens, Remix provides a mechanism for ensuring that server-only code is excluded from the client bundle; `.server` modules.
+Any modules with a directory named `.server` are never allowed into the module graph for the client.
+Similarly, files with a `.server` extension are also excluded from the client module graph.
+
+Theoretically, `.server` modules are a redundancy.
+A perfect module graph with perfect treeshaking shouldn't _need_ `.server` modules.
+But in practice, `.server` modules are indispensable.
+They are the only guaranteed way to exclude code from the client.
+
+### An imperfect optimization
+
+As we already discussed, even if treeshaking were perfect, it would still be a bad idea to rely on it to exclude server-only code.
+But treeshaking is a hard problem, especially in a language as dynamic as JavaScript.
+In the real world, treeshaking is not perfect.
+
+That's why treeshaking is designed to be an _optimization_ that slims down your bundle.
+Your code should already be correct before treeshaking is applied.
+Bundlers are allowed to make [their own tradeoffs about how much treeshaking][esbuild-minify-considerations] they want to do.
+And that shouldn't [affect Remix's implementation][remix-minify-syntax].
+They are even allowed to do _less_ treeshaking without needing a major version bump.
+
+Additionally, code can only be treeshaken if it is known to be side-effect free.
+Unfortunately, even fully side-effect free packages often omit `sideEffects: false` from their `package.json`.
+And sometimes side-effects are desired!
+What if there's a server-side package with side-effects that we want to include in our server bundle?
+How could we exclude that from the client bundle?
+There are ways, but they're all hacky and brittle.
+
+### Vite
+
+Remix is becoming a Vite plugin, but Vite's on-demand compilation in dev is incompatible with treeshaking.
+Since the compilation is on-demand, Vite only knows the _current_ importer for the module, not all possible importers.
+
+### Summary
+
+- Even if treeshaking were perfect, it leaves the door open for human error
+- `.server` modules guarantee that server-only code is excluded from the client
+- Treeshaking is an imperfect _optimization_, so a Remix app should work correctly and exclude server-only code even without treeshaking
+- Vite's architecture makes treeshaking in dev untenable
+
+## Decision
+
+Do not rely on implicit, cross-module treeshaking for correctness.
+Instead:
+
+- Forcibly remove server-only route exports and then explicitly run a dead-code elimination pass
+- Explicitly mark server-only code and throw a build time error if server code is still referenced in the client
+
+## Consequences
+
+- No reliance on optimizations for correctness
+- Build-time errors instead of runtime errors
+- Errors consistent across dev and prod with Vite
+- Exports are assumed to be client-safe unless explicitly marked as server-only
+  - For example, `.server` modules mark all their exports as server-only
+  - Route exports like `loader`, `action`, `headers`, etc. are an exception as they are already known to be server-only
+
+[virtual-modules]: https://github.com/remix-run/remix/blob/71f0e051d895807c349987655325c153903abad8/packages/remix-dev/compiler/js/plugins/routes.ts
+[ast-transforms]: https://github.com/remix-run/remix/pull/5259
+[esbuild-minify-considerations]: https://esbuild.github.io/api/#minify-considerations
+[remix-minify-syntax]: https://github.com/remix-run/remix/blob/bf042e7d340b3cbfdaa389c201e1284fb4d03403/packages/remix-dev/compiler/server/compiler.ts#L80-L88
diff --git a/decisions/0010-splitting-up-client-and-server-code-in-vite.md b/decisions/0010-splitting-up-client-and-server-code-in-vite.md
new file mode 100644
index 0000000000..70755110d7
--- /dev/null
+++ b/decisions/0010-splitting-up-client-and-server-code-in-vite.md
@@ -0,0 +1,102 @@
+# Splitting up client and server code in Vite
+
+Date: 2024-02-01
+
+Status: accepted
+
+## Context
+
+Before adopting Vite, Remix used to rely on ESbuild's treeshaking to implicitly separate client and server code.
+Even though Vite provides equivalent treeshaking (via Rollup) for builds, it does not perform cross-module treeshaking when running the dev server.
+In any case, we think its a [bad idea to rely on treeshaking for correctness][decision-0009].
+
+Goals:
+
+1. Simple and robust exclusion of server-only code from the client
+2. Prefer compile-time errors over runtime errors
+3. Typesafety for runtime errors
+4. Avoid performance degradation for common cases
+
+#### Remix's approach before Vite
+
+Remix already provides `.server` modules to explicitly separate client and server code at the module level (Goal 1 ✅).
+However, Remix's previous compiler replaced `.server` modules with empty modules.
+While this ensured that code from `.server` modules never leaks into the client,
+it also meant that any accidental references to imports from `.server` in the client
+would result in runtime errors, not compile-time errors (Goal 2 ❌).
+
+TypeScript does not understand that imports from `.server` modules may not exist on the client
+so typechecking does not catch these runtime errors (Goal 3 ❌).
+
+For example:
+
+```tsx
+import { getFortune } from "~/db.server.ts";
+
+export default function Route() {
+  const [fortune, setFortune] = useState(null);
+  return (
+    <>
+      {user ? (
+        <h1>Your fortune of the day: {fortune}</h1>
+      ) : (
+        <button onClick={() => setFortune(getFortune())}>
+          Open fortune cookie 🥠
+        </button>
+      )}
+    </>
+  );
+}
+```
+
+Your editor would not show any red squigglies, typechecking in CI would pass, and Remix would build your app without warnings or errors.
+But you've just shipped a bug that will crash your app anytime a user clicks the "Get user" button.
+
+#### How Vite's dev server works
+
+In development, Vite's dev server compiles requested JavaScript modules on the fly.
+As a result, Vite must decide how to transform each module without knowing the entire module graph.
+The Plugin API makes this apparent:[^1]
+
+- `resolveId` only provides the current `importer`
+- `load` and `transform` do not receive any information about the module graph
+
+This approach lets Vite load and transform each module _once_ and cache the result[^2] which is a keystone for its speed.
+
+#### Handling mixed modules
+
+While `.server` modules are a great way to separate client and server code in most cases,
+there will always be a need to stitch together modules that mix client and server code.
+For example, you may want to migrate from the previous compiler to Vite without needing to manually split up mixed modules.
+
+But supporting mixed modules directly in Remix would require compile-time magic which would add substantial complexity.
+Not only would it degrade performance for all users (Goal 4 ❌),
+but writing compile-time transforms that manipulate the AST is much more error-prone than throwing a compile-time error when `.server` modules are imported by client code.
+Depending on how its implemented, bugs in that compile-time magic could open the door to leaking server code into the client (Goal 1 ❌).
+
+## Decision
+
+- Support `.server` modules (including new `.server` directories) in Remix to split client and server code at the module-level (Goal 1 ✅)
+- Recommend [vite-env-only][vite-env-only] for expression-level separation (Goal 1 ✅)
+- For each Remix route module, remove server-only exports (`loader`, `action`, `headers`) and then explicitly run dead-code eliminate
+- Throw a compile-time error when `.server` modules remained after dead-code elimination (Goal 2 ✅)
+
+## Consequences
+
+Users are encouraged to primarily use `.server` modules but can always opt for more powerful, expression-level separation with [vite-env-only][vite-env-only].
+
+#### Typesafety
+
+Since Remix now throws when `.server` imports remain in the built client code, there are no remaining runtime errors to catch with typechecking for module-level separation (Goal 3 ✅).
+For expression-level separation, `vite-env-only` provides optional types (`<T>(_: T) => T | undefined`) which lets TypeScript prevent any runtime errors.
+
+#### Performance
+
+Checking for `.server` modules only requires checking the module's path and does not require AST parsing or transformations, so it's extremely fast (Goal 4 ✅).
+`vite-env-only` does require AST parsing and transformations so it will always be slower than `.server` modules.
+
+[^1]: Vite provides a lower-level module graph API, but the module graph is not guaranteed to be complete as it is only populated as modules are requested.
+[^2]: When a file changes on disk, Vite invalidates the corresponding module in its cache to power features like HMR.
+
+[decision-0009]: ./0009-do-not-rely-on-treeshaking-for-correctness.md
+[vite-env-only]: https://github.com/pcattori/vite-env-only