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/typescript.md
View on GitHub---
name: typescript
description: TypeScript configuration and type stripping in Node.js
metadata:
tags: typescript, type-stripping, ts-node, configuration
---
# TypeScript in Node.js
## Use Type Stripping
Node.js 22.6+ supports running TypeScript files directly by stripping types at runtime. In Node.js 23.6+ and 24+, type stripping is enabled by default.
### node.js 20.x and 22.x
Enable with the experimental flag:
```bash
node --experimental-strip-types app.ts
```
### Node.js 22.19+, 23.6+ and 24+
TypeScript files run directly without flags:
```bash
node app.ts
```
## Type Stripping Requirements
Type stripping works by removing type annotations without transforming code. Your TypeScript must follow these rules:
### Use Type-Only Imports
Always use `type` keyword for type imports:
```typescript
// GOOD - type-only import
import type { User, Config } from './types.ts';
import { createUser } from './user.ts';
// GOOD - inline type imports
import { createUser, type User } from './user.ts';
// BAD - may fail with type stripping
import { User, createUser } from './user.ts';
```
### No Enums
Enums require code transformation. Use const objects instead:
```typescript
// BAD - enums don't work with type stripping
enum Status {
Active = 'active',
Inactive = 'inactive',
}
// GOOD - const object with type
const Status = {
Active: 'active',
Inactive: 'inactive',
} as const;
type Status = (typeof Status)[keyof typeof Status];
```
### No Namespaces
Namespaces require transformation:
```typescript
// BAD - namespaces don't work
namespace Utils {
export function format(s: string): string {
return s.trim();
}
}
// GOOD - use modules
export function format(s: string): string {
return s.trim();
}
```
### No Constructor Parameter Properties
Parameter properties require transformation:
```typescript
// BAD - parameter properties don't work
class User {
constructor(public name: string, private age: number) {}
}
// GOOD - explicit property declaration
class User {
name: string;
private age: number;
constructor(name: string, age: number) {
this.name = name;
this.age = age;
}
}
```
### No Legacy Decorators
Use the TC39 decorator syntax (stage 3):
```typescript
// BAD - legacy/experimental decorators
@Injectable()
class Service {}
// Decorators support depends on Node.js version
// Check compatibility before using
```
## File Extensions
Use `.ts` extensions in imports. TypeScript will rewrite them to `.js` during build:
```typescript
// GOOD - .ts extension (works with type stripping, rewritten during build)
import { helper } from './helper.ts';
import type { Config } from './types.ts';
// JSON imports
import config from './config.json' with { type: 'json' };
```
## tsconfig.json for Development
Configure TypeScript for development with type stripping:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"noEmit": true,
"resolveJsonModule": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"allowImportingTsExtensions": true,
"lib": ["ES2022"],
"types": ["node"]
},
"include": ["src/**/*.ts", "test/**/*.ts"],
"exclude": ["node_modules"]
}
```
Key options:
- `noEmit`: No compilation, Node.js runs TypeScript directly
- `allowImportingTsExtensions`: Allow `.ts` imports
- `verbatimModuleSyntax`: Enforces type-only imports
- `isolatedModules`: Ensures compatibility with type stripping
## tsconfig.build.json for Publishing
Create a separate config for building distributable packages:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "dist",
"rootDir": "src",
"resolveJsonModule": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"allowImportingTsExtensions": true,
"rewriteRelativeImportExtensions": true,
"lib": ["ES2022"],
"types": ["node"]
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "test"]
}
```
Key build options:
- `rewriteRelativeImportExtensions`: Rewrites `.ts` imports to `.js` in output
- `declaration`: Generates `.d.ts` type declaration files
- `declarationMap`: Generates source maps for declarations
- `outDir`: Output directory for compiled files
## Running Tests
Use the built-in test runner with TypeScript:
```bash
# Node.js 22.19+/23.6+/24+
node --test test/*.test.ts
```
## Building for Distribution
Use `tsc` with the build config for publishing packages:
```bash
# Build with tsc
tsc -p tsconfig.build.json
```
## package.json Configuration
Configure package.json for ESM with TypeScript:
```json
{
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"files": ["dist", "README.md", "LICENSE"],
"scripts": {
"build": "tsc -p tsconfig.build.json",
"clean": "rm -rf dist",
"prepublishOnly": "npm run clean && npm run build",
"test": "node --test test/*.test.ts",
"typecheck": "tsc --noEmit"
},
"engines": {
"node": ">=22.6.0"
}
}
```
## Development Workflow
Run type checking separately since type stripping doesn't validate types:
```bash
# Check types without emitting
tsc --noEmit
# Watch mode for development
tsc --noEmit --watch
```
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 |