Skip to content

sb-dev/openquant / .agents/skills/node

Provides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.

FileKindSize
SKILL.mdskill md6.3 KB
rules/assets/graceful-server.test.tsscript2.6 KB
rules/assets/graceful-server.tsscript2.2 KB
rules/async-patterns.mdmarkdown3.1 KB
rules/caching.mdmarkdown4.8 KB
rules/environment.mdmarkdown6.0 KB
rules/error-handling.mdmarkdown3.8 KB
rules/flaky-tests.mdmarkdown10.4 KB
rules/graceful-shutdown.mdmarkdown4.6 KB
rules/logging.mdmarkdown4.4 KB
rules/modules.mdmarkdown2.0 KB
rules/node-modules-exploration.mdmarkdown3.6 KB
rules/performance.mdmarkdown2.8 KB
rules/profiling.mdmarkdown3.9 KB
rules/streams.mdmarkdown5.1 KB
rules/stuck-processes-and-tests.mdmarkdown3.9 KB
rules/testing.mdmarkdown4.4 KB
rules/typescript.mdmarkdown5.5 KB
tile.jsonconfig1017 B

rules/profiling.md

View on GitHub
---
name: profiling
description: Profiling and benchmarking tools
metadata:
  tags: profiling, benchmarking, performance, flame-graphs
---

# Profiling in Node.js

## Flame Graphs with @platformatic/flame

Use [@platformatic/flame](https://github.com/platformatic/flame) for CPU profiling with flame graph visualization:

```bash
npx @platformatic/flame app.ts
```

This starts your application with profiling enabled and generates an interactive flame graph.

### Markdown Output for AI Analysis

flame can output markdown reports suitable for AI-assisted performance analysis:

```bash
npx @platformatic/flame --output markdown app.ts
```

This enables a fully agentic workflow where you can:
1. Profile your application
2. Get markdown output describing hotspots
3. Feed the report to an AI assistant for optimization suggestions

### Programmatic Usage

```typescript
import { profile } from '@platformatic/flame';

const stop = await profile({
  outputFile: 'profile.html',
});

// Run your workload
await runBenchmark();

await stop();
```

## Load Testing Tools

### autocannon

Use [autocannon](https://github.com/mcollina/autocannon) for HTTP benchmarking:

```bash
# Basic benchmark
npx autocannon http://localhost:3000

# With options
npx autocannon -c 100 -d 30 -p 10 http://localhost:3000

# POST request with body
npx autocannon -m POST -H "Content-Type: application/json" -b '{"name":"test"}' http://localhost:3000/users
```

Options:
- `-c` - Number of concurrent connections (default: 10)
- `-d` - Duration in seconds (default: 10)
- `-p` - Number of pipelined requests (default: 1)
- `-m` - HTTP method
- `-b` - Request body

### Programmatic autocannon

```typescript
import autocannon from 'autocannon';

const result = await autocannon({
  url: 'http://localhost:3000',
  connections: 100,
  duration: 30,
  pipelining: 10,
});

console.log(autocannon.printResult(result));
```

### wrk

[wrk](https://github.com/wg/wrk) is a high-performance HTTP benchmarking tool:

```bash
# Basic benchmark
wrk -t12 -c400 -d30s http://localhost:3000

# With Lua script for custom requests
wrk -t12 -c400 -d30s -s post.lua http://localhost:3000
```

Options:
- `-t` - Number of threads
- `-c` - Number of connections
- `-d` - Duration
- `-s` - Lua script for custom logic

### k6

[k6](https://k6.io/) is ideal for complex load testing scenarios:

```javascript
// load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 100,
  duration: '30s',
};

export default function () {
  const res = http.get('http://localhost:3000');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 200ms': (r) => r.timings.duration < 200,
  });
  sleep(1);
}
```

```bash
k6 run load-test.js
```

## Built-in Node.js Profiling

### CPU Profiling

```bash
# Generate V8 profiling log
node --prof app.js

# Process the log
node --prof-process isolate-*.log > profile.txt
```

### Heap Snapshots

```bash
# Start with inspector
node --inspect app.js

# Then use Chrome DevTools (chrome://inspect) to:
# - Take heap snapshots
# - Record allocation timelines
# - Find memory leaks
```

### Diagnostic Reports

```bash
# Generate report on signal
node --report-on-signal app.js
kill -SIGUSR2 <pid>

# Generate report on uncaught exception
node --report-on-fatalerror app.js
```

## Profiling Workflow

1. **Establish baseline** - Run autocannon to get initial metrics
2. **Profile** - Use @platformatic/flame to identify hotspots
3. **Optimize** - Fix the identified bottlenecks
4. **Verify** - Run autocannon again to measure improvement
5. **Repeat** - Continue until performance goals are met

## Tool Comparison

| Tool | Best For |
|------|----------|
| @platformatic/flame | CPU profiling, flame graphs, AI-assisted analysis |
| autocannon | Quick HTTP benchmarks, Node.js native |
| wrk | Maximum throughput testing |
| k6 | Complex scenarios, CI/CD integration, scripted tests |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall