Faster TypeScript/JavaScript transformer without typechecking and node-gyp and postinstall script.
A TypeScript path alias resolver for Node.js applications that works seamlessly with both development (ts-node) and production environments. This package automatically resolves path aliases based on your tsconfig.json
configuration, eliminating the need for complex relative imports.
- π Automatic path resolution for both source (
src
) and compiled (dist
) directories - π― Full TypeScript path alias support via
tsconfig.json
with extends and module resolution - π ESM-first design with support for Node.js 20.6+
- π§ Zero configuration required - works out of the box
- π οΈ Utility functions for dynamic path resolution
- β¨ Support for TypeScript decorators and metadata reflection
- π Smart path alias resolution
- π Seamless development and production environments
- β‘οΈ Lightning fast performance with SWC
- π§ͺ Comprehensive test coverage
This package is:
- Designed primarily for backend applications and unit testing
- Currently in experimental status
- Requires thorough testing before production use
- Runtime sourcemap support via
sourceMap: true
intsconfig.json
for enhanced debugging
npm install --save @hyperse/ts-node
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist",
"baseUrl": "./",
"sourceMap": true,
"paths": {
"@utils/*": ["./src/utils/*"],
"@components/*": ["./src/components/*"],
"@config": ["./src/config.ts"]
}
}
}
For Node.js 20.6+:
{
"scripts": {
"dev": "node --import=@hyperse/ts-node/register ./src/index.ts",
"start": "node --import=@hyperse/ts-node/register ./dist/index.js"
}
}
For Node.js β€20.5 (deprecated):
{
"scripts": {
"dev": "node --loader @hyperse/ts-node/esm ./src/index.ts",
"start": "node --loader @hyperse/ts-node/esm ./dist/index.js"
}
}
Variable | Description | Default |
---|---|---|
HPS_TS_NODE_PROJECT |
Path to tsconfig file | tsconfig.json |
HPS_TS_NODE_LOG_LEVEL |
Log level [0-4] | 2 Info |
HPS_TS_NODE_LOG_TIMESTAMP |
Enable timestamp in logs | false |
Create a path resolver for your aliases:
import { createPathMatcher, HpsSpecifierLoader } from '@hyperse/ts-node';
import path from 'path';
const matcher = createPathMatcher('/project/root', {
'@utils/*': ['src/utils/*'],
'@components/*': ['src/components/*'],
});
// Resolve paths
const result = matcher('@utils/helper', {
extensions: ['.ts', '.js'],
// Optional: custom file existence checker
fileExists: (filePath) => filePath.includes('index'),
});
-
Path Aliases
- Keep aliases simple and intuitive
- Use consistent naming patterns
- Avoid conflicts with built-in module names
-
Project Structure
project/
βββ src/ # Source files
βββ dist/ # Compiled files
βββ tsconfig.json # TypeScript configuration
βββ package.json # Project configuration
- Requires a valid
tsconfig.json
file in the project root - Path resolution must be within the
rootDir
directory - All required properties must be accessible in the
tsconfig
inheritance chain - Not recommended for production use without thorough testing and validation
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.