sb-dev/openquant / .agents/skills/node
node
VerifiedProvides 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| rules/assets/graceful-server.test.ts | script | 2.6 KB |
| rules/assets/graceful-server.ts | script | 2.2 KB |
| rules/async-patterns.md | markdown | 3.1 KB |
| rules/caching.md | markdown | 4.8 KB |
| rules/environment.md | markdown | 6.0 KB |
| rules/error-handling.md | markdown | 3.8 KB |
| rules/flaky-tests.md | markdown | 10.4 KB |
| rules/graceful-shutdown.md | markdown | 4.6 KB |
| rules/logging.md | markdown | 4.4 KB |
| rules/modules.md | markdown | 2.0 KB |
| rules/node-modules-exploration.md | markdown | 3.6 KB |
| rules/performance.md | markdown | 2.8 KB |
| rules/profiling.md | markdown | 3.9 KB |
| rules/streams.md | markdown | 5.1 KB |
| rules/stuck-processes-and-tests.md | markdown | 3.9 KB |
| rules/testing.md | markdown | 4.4 KB |
| rules/typescript.md | markdown | 5.5 KB |
| tile.json | config | 1017 B |
rules/error-handling.md
View on GitHub---
name: error-handling
description: Error handling patterns in Node.js
metadata:
tags: errors, exceptions, try-catch, error-handling
---
# Error Handling in Node.js
## Custom Errors with @fastify/create-error
Use [@fastify/create-error](https://github.com/fastify/fastify-error) for creating custom errors with codes:
```typescript
import createError from '@fastify/create-error';
const NotFoundError = createError('NOT_FOUND', '%s not found', 404);
const ValidationError = createError('VALIDATION_ERROR', '%s', 400);
const DatabaseError = createError('DATABASE_ERROR', 'Database operation failed: %s', 500);
// Usage
throw new NotFoundError('User');
throw new ValidationError('Email is required');
```
## Minimal Error Code Implementation
If you prefer no dependencies, use this minimal pattern:
```typescript
interface AppErrorOptions {
code: string;
statusCode?: number;
cause?: Error;
}
function createAppError(message: string, options: AppErrorOptions): Error {
const error = new Error(message, { cause: options.cause });
(error as any).code = options.code;
(error as any).statusCode = options.statusCode ?? 500;
Error.captureStackTrace(error, createAppError);
return error;
}
// Factory functions for common errors
function notFound(resource: string): Error {
return createAppError(`${resource} not found`, { code: 'NOT_FOUND', statusCode: 404 });
}
function validationError(message: string): Error {
return createAppError(message, { code: 'VALIDATION_ERROR', statusCode: 400 });
}
function databaseError(message: string, cause?: Error): Error {
return createAppError(message, { code: 'DATABASE_ERROR', statusCode: 500, cause });
}
// Usage
throw notFound('User');
throw validationError('Email is required');
```
## Checking Error Codes
Check errors by code, not by class:
```typescript
function isAppError(error: unknown): error is Error & { code: string; statusCode: number } {
return error instanceof Error && 'code' in error && 'statusCode' in error;
}
try {
await fetchUser(id);
} catch (error) {
if (isAppError(error) && error.code === 'NOT_FOUND') {
return null;
}
throw error;
}
```
## Async Error Handling
Always use try-catch with async/await and propagate errors properly:
```typescript
async function fetchUser(id: string): Promise<User> {
try {
const user = await db.users.findById(id);
if (!user) {
throw notFound('User');
}
return user;
} catch (error) {
if (isAppError(error)) {
throw error;
}
throw databaseError('Failed to fetch user', error as Error);
}
}
```
## Unhandled Rejections and Exceptions
Do not handle `unhandledRejection` and `uncaughtException` manually. Use [close-with-grace](https://github.com/fastify/close-with-grace) which handles these automatically and triggers graceful shutdown.
See [graceful-shutdown.md](./graceful-shutdown.md) for proper shutdown handling.
## Fastify Error Handling
Fastify has built-in error handling:
```typescript
import Fastify from 'fastify';
const app = Fastify({ logger: true });
app.setErrorHandler((error, request, reply) => {
const statusCode = (error as any).statusCode ?? 500;
const code = (error as any).code ?? 'INTERNAL_ERROR';
request.log.error(error);
reply.status(statusCode).send({
error: {
code,
message: error.message,
},
});
});
```
## Never Swallow Errors
Never use empty catch blocks that hide errors:
```typescript
// BAD - error is swallowed
try {
await riskyOperation();
} catch (error) {
// Do nothing
}
// GOOD - handle or re-throw
try {
await riskyOperation();
} catch (error) {
logger.error({ err: error }, 'Operation failed');
throw error;
}
```
## Error Cause Chain
Use the `cause` option to preserve error chains:
```typescript
try {
await externalService.call();
} catch (error) {
throw new Error('Service call failed', { cause: error });
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |