Skip to content

PyModel/pythinker-code / .agents/skills/ts-performance-rules

ts-performance-rules

Verified

TypeScript and JavaScript performance and code-quality rules, usable in any framework. Use when writing, reviewing, or refactoring hot paths, data-structure choices, async flows, or bundle-size-sensitive code. Triggers include "optimize this function", "too slow", "reduce allocations", "bundle size", "lazy load", "speed up imports", or general code review of utilities and services.

rules/js-request-idle-callback.md

View on GitHub
---
title: Defer Non-Critical Work with requestIdleCallback
impact: MEDIUM
impactDescription: keeps UI responsive during background tasks
tags: javascript, performance, idle, scheduling, analytics
---

## Defer Non-Critical Work with requestIdleCallback

**Impact: MEDIUM (keeps UI responsive during background tasks)**

Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.

**Incorrect (blocks main thread during user interaction):**

```typescript
function handleSearch(query: string) {
  const results = searchItems(query);
  setResults(results);

  // These block the main thread immediately
  analytics.track("search", { query });
  saveToRecentSearches(query);
  prefetchTopResults(results.slice(0, 3));
}
```

**Correct (defers non-critical work to idle time):**

```typescript
function handleSearch(query: string) {
  const results = searchItems(query);
  setResults(results);

  // Defer non-critical work to idle periods
  requestIdleCallback(() => {
    analytics.track("search", { query });
  });

  requestIdleCallback(() => {
    saveToRecentSearches(query);
  });

  requestIdleCallback(() => {
    prefetchTopResults(results.slice(0, 3));
  });
}
```

**With timeout for required work:**

```typescript
// Ensure analytics fires within 2 seconds even if browser stays busy
requestIdleCallback(() => analytics.track("page_view", { path: location.pathname }), {
  timeout: 2000,
});
```

**Chunking large tasks:**

```typescript
function processLargeDataset(items: Item[]) {
  let index = 0;

  function processChunk(deadline: IdleDeadline) {
    // Process items while we have idle time (aim for <50ms chunks)
    while (index < items.length && deadline.timeRemaining() > 0) {
      processItem(items[index]);
      index++;
    }

    // Schedule next chunk if more items remain
    if (index < items.length) {
      requestIdleCallback(processChunk);
    }
  }

  requestIdleCallback(processChunk);
}
```

**With fallback for unsupported browsers:**

```typescript
const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1));

scheduleIdleWork(() => {
  // Non-critical work
});
```

**When to use:**

- Analytics and telemetry
- Saving state to localStorage/IndexedDB
- Prefetching resources for likely next actions
- Processing non-urgent data transformations
- Lazy initialization of non-critical features

**When NOT to use:**

- User-initiated actions that need immediate feedback
- Rendering updates the user is waiting for
- Time-sensitive operations
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 implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall