docs: file convention updates

docs/file-conventions/-client.md

@@ -0,0 +1,26 @@
+---
+title: "*.client.ts extension"
+---
+
+# `*.client.ts`
+
+While uncommon, you may have a file or dependency that needs uses module side-effects in the browser. You can use `*.client.ts` on file names to force them out of server bundles.
+
+```ts filename=feature-check.client.ts
+// this would break the server
+export const supportsVibrationAPI = "vibrate" in window.navigator;
+```
+
+Note that values exported from this module will all be `undefined` on the server, so the only places to use them are in `useEffect` and user events like click handlers.
+
+```ts
+import { supportsVibrationAPI } from "./feature-check.client.ts";
+
+console.log(supportsVibrationAPI);
+// server: undefined
+// client: true | false
+```
+
+See [Route Module][routemodule] for more information.
+
+[routemodule]: ../route/route-module

docs/file-conventions/-server.md

@@ -0,0 +1,11 @@
+---
+title: "*.server.ts extension"
+---
+
+# `*.server.ts`
+
+While not always necessary, you can use `*.server.ts` on file names to force them out of client bundles. Usually the compiler is fine, but if you've got a server dependency with module side-effects, move it into a `your-name.server.ts` file to ensure it is removed from client bundles.
+
+See [Route Module][routemodule] for more information.
+
+[routemodule]: ../route/route-module

docs/file-conventions/entry.client.md

@@ -7,4 +7,25 @@ toc: false
 
 By default, Remix will handle hydrating your app on the client for you. If you want to customize this behavior, you can run `npx remix reveal` to generate a `app/entry.client.tsx` (or `.jsx`) that will take precedence. This file is the entry point for the browser and is responsible for hydrating the markup generated by the server in your [server entry module][server-entry-module], however you can also initialize any other client-side code here.
 
+Typically this module uses `ReactDOM.hydrateRoot` to hydrate the markup that was already generated on the server in your [server entry module][server-entry-module].
+
+Here's a basic example:
+
+```tsx
+import { RemixBrowser } from "@remix-run/react";
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <RemixBrowser />
+    </StrictMode>
+  );
+});
+```
+
+This is the first piece of code that runs in the browser. You can initialize client side libraries, add client only providers, etc.
+
 [server-entry-module]: ./entry.server

docs/file-conventions/index.md

@@ -1,4 +1,4 @@
 ---
 title: File Conventions
-order: 10
+order: 5
 ---