Merge branch 'main' into markdown-relative-links

Author: lachlancollins

.gitignore

@@ -1,7 +1,7 @@
 node_modules
 package-lock.json
 yarn.lock
-convex/generated
+drizzle/migrations
 
 .tanstack
 .DS_Store

.prettierignore

@@ -3,8 +3,6 @@
 **/public
 pnpm-lock.yaml
 routeTree.gen.ts
-convex/_generated
-convex/README.md
 src/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query.md
 .content-collections
 .claude

.tanstack-start/server-routes/routeTree.gen.ts

@@ -72,3 +72,94 @@ loader: async ({ deps }) => {
 ```
 
 This ensures the loader only re-runs when the specific dependencies change, not when unrelated search params (like `expanded`, `viewMode`, etc.) change.
+
+### Loaders Are Isomorphic
+
+**Loaders in TanStack Start/Router are isomorphic and cannot call server logic unless via a call to a server function.**
+
+Loaders run on both the server and client, so they cannot directly access server-only APIs (like file system, database connections, etc.). To perform server-side operations, loaders must call server functions (e.g., TanStack server functions created via `createServerFn()`, Convex queries/mutations, API routes, or other server functions).
+
+❌ **Bad:**
+
+```typescript
+loader: async () => {
+  // This won't work - direct server API access
+  const data = await fs.readFile('data.json')
+  return { data }
+}
+```
+
+✅ **Good:**
+
+```typescript
+loader: async () => {
+  // Call a server function instead (TanStack server function or Convex)
+  // TanStack server functions created via createServerFn() can be called directly
+  const data = await serverFn({ data: { id: '123' } })
+  // or
+  const data = await convex.query(api.data.getData)
+  return { data }
+}
+```
+
+## Server-Only Code and Environment Shaking
+
+### TanStack Start Environment Shaking
+
+**TanStack Start performs environment shaking - any code not referenced by a `createServerFn` handler is stripped from the client build.**
+
+This means:
+
+- Server-only code (database, file system, etc.) is automatically excluded from client bundles
+- Only code inside `createServerFn` handlers is included in server bundles
+- Code outside handlers is included in both server and client bundles
+
+### Importing Server Functions
+
+**Server functions wrapped in `createServerFn` can be safely imported statically in route files.**
+
+❌ **Bad - Dynamic imports in component code:**
+
+```typescript
+// In a route component
+const rolesQuery = useQuery({
+  queryFn: async () => {
+    const { listRoles } = await import('~/utils/roles.server')
+    return listRoles({ data: {} })
+  },
+})
+```
+
+This causes bundler issues because dynamic imports can't be properly tree-shaken, potentially pulling server-only code (like `Buffer`, `drizzle`, `postgres`) into the client bundle.
+
+✅ **Good - Static imports:**
+
+```typescript
+// At the top of the route file
+import { listRoles } from '~/utils/roles.server'
+
+// In component code
+const rolesQuery = useQuery({
+  queryFn: async () => {
+    return listRoles({ data: {} })
+  },
+})
+```
+
+Since `listRoles` is wrapped in `createServerFn`, TanStack Start will properly handle environment shaking and exclude server-only dependencies from the client bundle.
+
+### Rules for Server-Only Imports
+
+1. **Server functions** (`createServerFn` wrappers) can be imported statically anywhere
+2. **Direct server-only code** (database clients, file system, etc.) must ONLY be imported:
+   - Inside `createServerFn` handlers
+   - In separate server-only files (e.g., `*.server.ts`)
+   - Never use dynamic imports (`await import()`) for server-only code in component code
+
+## Development & Build Commands
+
+### Use `build` for Testing Build Output
+
+**The `dev` command does not end - it runs indefinitely in watch mode.**
+
+When agents need to test build output or verify that the project builds successfully, use the `build` command instead of `dev`. The `build` command will complete and exit, making it suitable for automated testing and verification.