@runweave/server-linux-x64 0.1.8 → 0.1.9

package/payload/plugins/toolkit/skills/react-best-practices/README.md

@@ -0,0 +1,127 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Rule files grouped by category
+  - `meta/sections.md` - Section metadata (titles, impacts, descriptions)
+  - `meta/template.md` - Template for creating new rules
+  - `<category>/<description>.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+- **`test-cases.json`** - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Build AGENTS.md from rules:
+
+   ```bash
+   pnpm build
+   ```
+
+3. Validate rule files:
+
+   ```bash
+   pnpm validate
+   ```
+
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+
+## Creating a New Rule
+
+1. Copy `rules/meta/template.md` into the appropriate category directory.
+2. Choose the category directory matching the section:
+   - `async/` for Eliminating Waterfalls (Section 1)
+   - `bundle/` for Bundle Size Optimization (Section 2)
+   - `server/` for Server-Side Performance (Section 3)
+   - `client/` for Client-Side Data Fetching (Section 4)
+   - `rerender/` for Re-render Optimization (Section 5)
+   - `rendering/` for Rendering Performance (Section 6)
+   - `js/` for JavaScript Performance (Section 7)
+   - `advanced/` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+````markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+````
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files under `meta/` are support files and are excluded from rule lists.
+- Rule files use `<category>/<description>.md` (for example, `async/parallel.md`).
+- The parent directory identifies the section.
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Put the file in the correct category directory.
+2. Follow the `meta/template.md` structure.
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).

package/payload/plugins/toolkit/skills/react-best-practices/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 62 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category                  | Impact      | Directory    |
+| -------- | ------------------------- | ----------- | ------------ |
+| 1        | Eliminating Waterfalls    | CRITICAL    | `async/`     |
+| 2        | Bundle Size Optimization  | CRITICAL    | `bundle/`    |
+| 3        | Server-Side Performance   | HIGH        | `server/`    |
+| 4        | Client-Side Data Fetching | MEDIUM-HIGH | `client/`    |
+| 5        | Re-render Optimization    | MEDIUM      | `rerender/`  |
+| 6        | Rendering Performance     | MEDIUM      | `rendering/` |
+| 7        | JavaScript Performance    | LOW-MEDIUM  | `js/`        |
+| 8        | Advanced Patterns         | LOW         | `advanced/`  |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async/defer-await` - Move await into branches where actually used
+- `async/parallel` - Use Promise.all() for independent operations
+- `async/dependencies` - Use better-all for partial dependencies
+- `async/api-routes` - Start promises early, await late in API routes
+- `async/suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle/barrel-imports` - Import directly, avoid barrel files
+- `bundle/dynamic-imports` - Use next/dynamic for heavy components
+- `bundle/defer-third-party` - Load analytics/logging after hydration
+- `bundle/conditional` - Load modules only when feature is activated
+- `bundle/preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server/auth-actions` - Authenticate server actions like API routes
+- `server/cache-react` - Use React.cache() for per-request deduplication
+- `server/cache-lru` - Use LRU cache for cross-request caching
+- `server/dedup-props` - Avoid duplicate serialization in RSC props
+- `server/hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server/serialization` - Minimize data passed to client components
+- `server/parallel-fetching` - Restructure components to parallelize fetches
+- `server/after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client/swr-dedup` - Use SWR for automatic request deduplication
+- `client/event-listeners` - Deduplicate global event listeners
+- `client/passive-event-listeners` - Use passive listeners for scroll
+- `client/localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender/defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender/memo` - Extract expensive work into memoized components
+- `rerender/memo-with-default-value` - Hoist default non-primitive props
+- `rerender/dependencies` - Use primitive dependencies in effects
+- `rerender/derived-state` - Subscribe to derived booleans, not raw values
+- `rerender/derived-state-no-effect` - Derive state during render, not effects
+- `rerender/functional-setstate` - Use functional setState for stable callbacks
+- `rerender/lazy-state-init` - Pass function to useState for expensive values
+- `rerender/simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender/move-effect-to-event` - Put interaction logic in event handlers
+- `rerender/transitions` - Use startTransition for non-urgent updates
+- `rerender/use-ref-transient-values` - Use refs for transient frequent values
+- `rerender/no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering/animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering/content-visibility` - Use content-visibility for long lists
+- `rendering/hoist-jsx` - Extract static JSX outside components
+- `rendering/svg-precision` - Reduce SVG coordinate precision
+- `rendering/hydration-no-flicker` - Use inline script for client-only data
+- `rendering/hydration-suppress-warning` - Suppress expected mismatches
+- `rendering/activity` - Use Activity component for show/hide
+- `rendering/conditional-render` - Use ternary, not && for conditionals
+- `rendering/usetransition-loading` - Prefer useTransition for loading state
+- `rendering/resource-hints` - Use React DOM resource hints for preloading
+- `rendering/script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js/batch-dom-css` - Group CSS changes via classes or cssText
+- `js/index-maps` - Build Map for repeated lookups
+- `js/cache-property-access` - Cache object properties in loops
+- `js/cache-function-results` - Cache function results in module-level Map
+- `js/cache-storage` - Cache localStorage/sessionStorage reads
+- `js/combine-iterations` - Combine multiple filter/map into one loop
+- `js/length-check-first` - Check array length before expensive comparison
+- `js/early-exit` - Return early from functions
+- `js/hoist-regexp` - Hoist RegExp creation outside loops
+- `js/min-max-loop` - Use loop for min/max instead of sort
+- `js/set-map-lookups` - Use Set/Map for O(1) lookups
+- `js/tosorted-immutable` - Use toSorted() for immutability
+- `js/flatmap-filter` - Use flatMap to map and filter in one pass
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced/event-handler-refs` - Store event handlers in refs
+- `advanced/init-once` - Initialize app once per app load
+- `advanced/use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async/parallel.md
+rules/bundle/barrel-imports.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

package/payload/plugins/toolkit/skills/react-best-practices/metadata.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}

package/payload/plugins/toolkit/skills/react-best-practices/rules/advanced/event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler);
+    return () => window.removeEventListener(event, handler);
+  }, [event, handler]);
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e);
+    window.addEventListener(event, listener);
+    return () => window.removeEventListener(event, listener);
+  }, [event]);
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler);
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent);
+    return () => window.removeEventListener(event, onEvent);
+  }, [event]);
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

package/payload/plugins/toolkit/skills/react-best-practices/rules/advanced/init-once.md

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false;
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return;
+    didInit = true;
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

package/payload/plugins/toolkit/skills/react-best-practices/rules/advanced/use-latest.md

@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState("");
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300);
+    return () => clearTimeout(timeout);
+  }, [query, onSearch]);
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState("");
+  const onSearchEvent = useEffectEvent(onSearch);
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300);
+    return () => clearTimeout(timeout);
+  }, [query]);
+}
+```

package/payload/plugins/toolkit/skills/react-best-practices/rules/async/api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth();
+  const config = await fetchConfig();
+  const data = await fetchData(session.user.id);
+  return Response.json({ data, config });
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth();
+  const configPromise = fetchConfig();
+  const session = await sessionPromise;
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id),
+  ]);
+  return Response.json({ data, config });
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

package/payload/plugins/toolkit/skills/react-best-practices/rules/async/defer-await.md

@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId);
+
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true };
+  }
+
+  // Only this branch uses userData
+  return processUserData(userData);
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true };
+  }
+
+  // Fetch only when needed
+  const userData = await fetchUserData(userId);
+  return processUserData(userData);
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId);
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  const permissions = await fetchPermissions(userId);
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

package/payload/plugins/toolkit/skills/react-best-practices/rules/async/dependencies.md

@@ -0,0 +1,52 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
+const profile = await fetchProfile(user.id);
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from "better-all";
+
+const { user, config, profile } = await all({
+  async user() {
+    return fetchUser();
+  },
+  async config() {
+    return fetchConfig();
+  },
+  async profile() {
+    return fetchProfile((await this.$.user).id);
+  },
+});
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser();
+const profilePromise = userPromise.then((user) => fetchProfile(user.id));
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise,
+]);
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

package/payload/plugins/toolkit/skills/react-best-practices/rules/async/parallel.md

@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser();
+const posts = await fetchPosts();
+const comments = await fetchComments();
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments(),
+]);
+```