https://github.com/hyperse-io/ts-node
Faster TypeScript/JavaScript transformer without typechecking and node-gyp and postinstall script.
https://github.com/hyperse-io/ts-node
hyperse monorepo nodejs swc-node ts-alias ts-node ts-node-esm tsconfig typescript typescript-compiler typescript-node
Last synced: about 2 months ago
JSON representation
Faster TypeScript/JavaScript transformer without typechecking and node-gyp and postinstall script.
- Host: GitHub
- URL: https://github.com/hyperse-io/ts-node
- Owner: hyperse-io
- License: mit
- Created: 2024-05-25T09:09:19.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-06T09:39:45.000Z (7 months ago)
- Last Synced: 2025-06-09T03:33:33.132Z (7 months ago)
- Topics: hyperse, monorepo, nodejs, swc-node, ts-alias, ts-node, ts-node-esm, tsconfig, typescript, typescript-compiler, typescript-node
- Language: TypeScript
- Homepage:
- Size: 4.29 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# @hyperse/ts-node
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.
## Features
- 🔄 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
## ⚠️ Important Notice
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` in `tsconfig.json` for enhanced debugging
## Installation
```bash
npm install --save @hyperse/ts-node
```
## Quick Start
### 1. Configure `tsconfig.json`
```json
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist",
"baseUrl": "./",
"sourceMap": true,
"paths": {
"@utils/*": ["./src/utils/*"],
"@components/*": ["./src/components/*"],
"@config": ["./src/config.ts"]
}
}
}
```
### 2. Usage in ESM Projects
For Node.js 20.6+:
```json
{
"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):
```json
{
"scripts": {
"dev": "node --loader @hyperse/ts-node/esm ./src/index.ts",
"start": "node --loader @hyperse/ts-node/esm ./dist/index.js"
}
}
```
## Environment Variables
| 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` |
## API Reference
### `createPathMatcher()`
Create a path resolver for your aliases:
```ts
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'),
});
```
## Best Practices
1. **Path Aliases**
- Keep aliases simple and intuitive
- Use consistent naming patterns
- Avoid conflicts with built-in module names
2. **Project Structure**
```text
project/
├── src/ # Source files
├── dist/ # Compiled files
├── tsconfig.json # TypeScript configuration
└── package.json # Project configuration
```
## Limitations
1. Requires a valid `tsconfig.json` file in the project root
2. Path resolution must be within the `rootDir` directory
3. All required properties must be accessible in the `tsconfig` inheritance chain
4. Not recommended for production use without thorough testing and validation
## Contributing
Contributions are welcome! Please read our [contributing guidelines](https://github.com/hyperse-io/.github/blob/main/CONTRIBUTING.md) before submitting pull requests.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.