existential-birds/beagle / plugins/beagle-react/skills/remix-v2-perf-ssr-review
remix-v2-perf-ssr-review
VerifiedReviews Remix v2 code for caching header misuse, missing server/client split, hydration mismatches (Date, Math.random, locale), prefetch hygiene, and asset bottlenecks. Use when reviewing routes that export headers, use .server.ts/.client.ts, or render dates/IDs in a Remix v2 codebase.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.4 KB |
| references/assets.md | markdown | 7.5 KB |
| references/caching-headers.md | markdown | 9.0 KB |
| references/hydration.md | markdown | 10.3 KB |
| references/prefetch-streaming.md | markdown | 8.6 KB |
| references/server-client-split.md | markdown | 9.1 KB |
references/server-client-split.md
View on GitHub# Server/Client Split Review
Anti-patterns in `.server.ts` / `.client.ts` boundaries, env var access, and module hygiene.
## What to flag
### 1. Server library imported in a route file without `.server.ts`
Remix's compiler strips `loader`, `action`, and `headers` from the client bundle along with the dependencies used **inside them** — but only if those dependencies have no module side effects. A top-level `new PrismaClient()`, an `initializeApp()` call, or even a `console.log` defeats tree-shaking. The dep leaks into the client bundle, breaks the build at runtime, or worse, ships secrets.
**Bad:**
```tsx
// app/lib/db.ts -- no .server suffix
import { PrismaClient } from "@prisma/client";
export const prisma = new PrismaClient(); // top-level side effect
// app/routes/users.tsx
import { prisma } from "~/lib/db"; // leaks into client graph
```
**Good:**
```tsx
// app/lib/db.server.ts -- never reaches client bundle
import { PrismaClient } from "@prisma/client";
export const prisma = new PrismaClient();
// app/routes/users.tsx
import { prisma } from "~/lib/db.server";
```
**Report as:** `[FILE:LINE] SERVER_LIB_WITHOUT_SERVER_SUFFIX` — `<lib>` imported from a non-`.server` module reachable from the client graph.
**Common server-only imports to scan for:** `@prisma/client`, `prisma`, `bcrypt`, `bcryptjs`, `argon2`, `jsonwebtoken`, `node:fs`, `node:path`, `node:crypto`, `fs`, `path`, `redis`, `ioredis`, `mongodb`, `pg`, `mysql2`, `aws-sdk`, `@aws-sdk/*`, `nodemailer`, `stripe` (server SDK — `@stripe/stripe-js` is the client version).
### 2. Secret env vars referenced in a component body or non-`.server` utility
`process.env` does not exist in the browser. References from a component body either crash at runtime, get inlined as `undefined`, or — worst case — get inlined as the actual secret string by some bundlers / Vite plugins.
**Bad:**
```tsx
// app/components/Checkout.tsx
export function Checkout() {
const key = process.env.STRIPE_SECRET_KEY; // leaks to client
return <CheckoutForm secretKey={key} />;
}
```
**Bad (transitive leak):**
```tsx
// app/lib/stripe.ts -- no .server suffix
export const stripeKey = process.env.STRIPE_SECRET_KEY;
```
**Good:** read secrets only inside loaders/actions, or inside a `.server.ts` module:
```tsx
// app/lib/stripe.server.ts
import Stripe from "stripe";
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
```
**Report as:** `[FILE:LINE] SECRET_ENV_LEAK` — `process.env.<NAME>` read from a non-`.server` module reachable from the client graph.
**Scan for env names containing:** `SECRET`, `PRIVATE_KEY`, `TOKEN`, `PASSWORD`, `DATABASE_URL`, `API_KEY` (any provider), `JWT_*`, `WEBHOOK_SECRET`, `SESSION_SECRET`.
### 3. Raw `process.env` returned from root loader to client
Returning `process.env` (or even a large subset) from the root loader exposes every environment variable to every visitor as part of `window.ENV`. Common variant: spreading `...process.env` into a returned object.
**Bad:**
```tsx
// app/root.tsx
export async function loader() {
return json({ ENV: process.env }); // every secret to every browser
}
```
**Also bad:**
```tsx
return json({ ENV: { ...process.env, EXTRA: "x" } });
```
**Good:** explicit whitelist of public keys only:
```tsx
return json({
ENV: {
STRIPE_PUBLIC_KEY: process.env.STRIPE_PUBLIC_KEY,
POSTHOG_KEY: process.env.POSTHOG_KEY,
PUBLIC_API_URL: process.env.PUBLIC_API_URL,
},
});
```
**Report as:** `[FILE:LINE] PROCESS_ENV_RETURNED_FROM_LOADER` — entire `process.env` (or a spread of it) returned from a loader.
### 4. `typeof window === "undefined"` used as a substitute for `.server.ts`
Treeshaking is unreliable. A common pattern is to gate server code with `typeof window === "undefined"` at module top level — but the dead branch still pulls server deps into the client graph because the static `import` is hoisted regardless. The bundle either grows by megabytes, breaks at build time, or surfaces secrets.
**Bad:**
```tsx
// app/lib/logger.ts
import { createLogger } from "pino"; // hoisted import — always in client bundle
const logger = typeof window === "undefined"
? createLogger({ level: "info" })
: { info: console.log, error: console.error };
export { logger };
```
**Good (split files):**
```tsx
// app/lib/logger.server.ts
import { createLogger } from "pino";
export const logger = createLogger({ level: "info" });
// app/lib/logger.client.ts
export const logger = { info: console.log, error: console.error };
// Import the right one from a route based on where it runs:
// loader: import { logger } from "~/lib/logger.server";
// component effect: import { logger } from "~/lib/logger.client";
```
**Good (function-body branch — acceptable for isomorphic helpers that don't import server libs):**
```tsx
export function getEnvLabel(): "server" | "client" {
return typeof window === "undefined" ? "server" : "client";
}
```
**Report as:** `[FILE:LINE] TYPEOF_WINDOW_INSTEAD_OF_SERVER_SUFFIX` — module top-level branches on `typeof window` but still imports server-only deps.
### 5. Higher-order function wrapping a loader
`export const loader = withAuth(async (args) => { ... })` evaluates `withAuth` at module load — a module-level side effect that pins server-only deps into the client graph. The compiler's `loader` stripping can't see through the wrapper.
**Bad:**
```tsx
import { withAuth } from "~/lib/auth"; // wrapper imports prisma at top
export const loader = withAuth(async ({ params }) => { /* ... */ });
```
**Good (call the helper inside the loader body):**
```tsx
import type { LoaderFunctionArgs } from "@remix-run/node";
import { requireAuth } from "~/lib/auth.server";
export async function loader(args: LoaderFunctionArgs) {
await requireAuth(args);
// ...
}
```
**Report as:** `[FILE:LINE] HOF_WRAPPING_LOADER` — `loader` (or `action`) is wrapped in a higher-order function; helpers should be called inside the body.
### 6. `.client.ts` module imported into a server-only path
`.client.ts` modules are stripped from the server bundle — their exports are `undefined` during SSR. If a loader, action, or `.server` module imports from `.client.ts`, calls into it will throw `Cannot read properties of undefined`.
**Bad:**
```tsx
// app/lib/analytics.client.ts
export function track(event: string) { window.posthog.capture(event); }
// app/routes/checkout.tsx
import { track } from "~/lib/analytics.client";
export async function loader() {
track("checkout_loaded"); // undefined.call during SSR — crash
return null;
}
```
**Good:** call `.client` code only inside `useEffect`/event handlers:
```tsx
import { useEffect } from "react";
import { track } from "~/lib/analytics.client";
export default function Checkout() {
useEffect(() => track("checkout_loaded"), []);
return <CheckoutForm />;
}
```
**Report as:** `[FILE:LINE] CLIENT_MODULE_USED_ON_SERVER` — `.client.ts` import called from loader/action/`.server` module.
### 7. Secret env in a `links` or `meta` export
`links` and `meta` exports run on both server and client. References to `process.env.SECRET_*` inside them will be inlined into the client document.
**Bad:**
```tsx
export const meta: MetaFunction = () => [
{ name: "x-admin-token", content: process.env.ADMIN_TOKEN }, // leaked
];
```
**Good:** never read secrets in `links`/`meta`. If a route's meta legitimately depends on server-side config, return the value from the loader and read it via `useLoaderData()` in the component (not in `meta`, which receives only loader data anyway):
```tsx
export const meta: MetaFunction<typeof loader> = ({ data }) => [
{ name: "x-feature", content: data?.featureFlag ?? "" },
];
```
**Report as:** `[FILE:LINE] SECRET_ENV_IN_META_OR_LINKS` — secret env value referenced in `meta` or `links` export.
## Verify before flagging
- For "server lib without `.server.ts`," confirm the importing file is reachable from the client graph (route module, non-`.server` utility transitively imported by a component). Imports from inside another `.server.ts` are fine.
- For "secret env leak," confirm the env name actually looks secret. `STRIPE_PUBLIC_KEY`, `POSTHOG_KEY`, `PUBLIC_API_URL` are conventionally public. `STRIPE_SECRET_KEY`, `JWT_SECRET`, `DATABASE_URL` are conventionally private. If the project uses a different convention (`NEXT_PUBLIC_*`, `PUBLIC_*`, `VITE_*`), note that.
- For "`typeof window` substitute," confirm the file actually imports server deps. A pure isomorphic helper that branches on `typeof window` is fine — the issue is the static import at the top.
- For "HOF wrapping loader," confirm the wrapper actually imports server deps. A trivial type-only wrapper is fine.
- For "client module used on server," confirm the call site is in loader/action/`.server` code, not in `useEffect`/handler/`<ClientOnly>`.
## Verbatim quote requirements
Findings on this surface require a verbatim quote of:
- the `import` statement being flagged, OR
- the `process.env.<NAME>` reference being flagged, AND
- the surrounding context (file path + whether the call site is loader/action/component body/effect/handler).
A finding like "this file leaks prisma to the client" with no import path or call site is not reportable.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |