@rws-framework/tsc NPM

@rws-framework/tsc

A TypeScript compilation and transpilation utility for the RWS (Realtime Web Suite) framework. This package provides advanced TypeScript compilation capabilities with webpack bundling, caching, CLI integration, and enhanced runtime features.

Overview

@rws-framework/tsc is a specialized TypeScript compiler that extends standard TypeScript compilation with webpack bundling, intelligent caching, and seamless integration with the RWS framework ecosystem. It's designed to transpile TypeScript applications into optimized, executable JavaScript bundles for CLI and server environments.

Features

Advanced TypeScript Compilation: Full TypeScript support with decorators, metadata emission, and modern ES features
Webpack Integration: Sophisticated webpack configuration with optimized bundling for Node.js environments
Enhanced Runtime Features:
- Proper __dirname and __filename handling in transpiled files
- Dynamic import support with on-demand transpilation
Intelligent Caching: MD5-based cache warming system to avoid unnecessary recompilation
CLI Integration: Comprehensive command-line interface with multiple commands and options
Path Mapping: Support for TypeScript path mapping and module resolution
External Dependencies: Smart handling of external modules and Node.js built-ins
Development Mode: Support for both development and production builds
Source Maps: Optional source map generation for debugging

Installation

npm install @rws-framework/tsc

Usage

CLI Usage

The package provides a comprehensive CLI command rws-tsc with multiple commands and options:

npx rws-tsc [command] [options]

Available Commands

`transpile <runspaceDir> [options]`

Transpile TypeScript files in the specified directory.

# Basic usage
rws-tsc transpile ./my-project

# With custom entry point
rws-tsc transpile ./my-project --entry src/main.ts

# Production build with custom output
rws-tsc transpile ./my-project --entry src/app.ts --prod --build-dir ./dist --out-file app.js

Options:

--entry <path>: Entry file path (default: src/index.ts)
--build-dir <path>: Build output directory (default: {runspaceDir}/build)
--out-file <name>: Output filename (default: main.cli.rws.js)
--prod: Production mode - optimized build without source maps (default: development mode)

`help`

Show help information and available commands.

rws-tsc help
# or
rws-tsc --help
# or
rws-tsc -h

Legacy CLI Options

For backward compatibility, the following global options are still supported:

--verbose: Enable verbose logging output
--reload: Force cache reload and rebuild

Programmatic API

import { transpile, dynamicImportTs } from '@rws-framework/tsc';

const result = await transpile({
    runspaceDir: '/path/to/your/project',
    entries: { main: 'src/index.ts' },
    buildDir: 'build',
    outFileName: 'main.cli.rws.js',
    tsPaths: {
        '@/*': ['src/*'],
        '@utils/*': ['src/utils/*']
    },
    isDev: false
});

console.log('Transpiled binary path:', result.transpiledBinPath);

// Dynamic import helper for runtime transpilation
const module = await dynamicImportTs('./some-file', srcDir, buildDir, runspaceDir);

Configuration Options

TranspileOptions

Option	Type	Default	Description
`runspaceDir`	`string`	required	Root directory of the project to transpile
`entries`	`object`	`{ main: 'src/index.ts' }`	Entry points for webpack bundling
`buildDir`	`string`	`{runspaceDir}/build`	Output directory for compiled files
`outFileName`	`string`	`'main.cli.rws.js'`	Name of the output file
`tsPaths`	`object`	`{}`	TypeScript path mapping configuration
`isDev`	`boolean`	`false`	Enable development mode with source maps

Enhanced Runtime Features

Proper `dirname` and `filename` Handling

The package includes custom webpack plugins that ensure __dirname and __filename in transpiled files point to the source directory structure rather than the execution directory:

// In your TypeScript source file (src/utils/helper.ts)
const configPath = path.join(__dirname, '../config.json');
// After transpilation, __dirname will correctly point to the source directory

Dynamic Import Support

The package transforms await import() statements to support on-demand TypeScript transpilation:

// In your TypeScript source
const module = await import('./dynamic-module');

// Gets transformed to use the helper function for runtime transpilation
const module = await require('@rws-framework/tsc').dynamicImportTs('./dynamic-module', srcDir, buildDir, runspaceDir);

Architecture

Core Components

1. Transpilation Engine (`console.ts`)

Main transpilation orchestrator with CLI command handling
Handles cache warming and build coordination
Executes the final transpiled binary

2. Build System (`inc/build.ts`)

Webpack-based compilation pipeline
Asset generation and optimization
Error handling and reporting

3. Webpack Configuration (`inc/webpack.ts`)

Advanced webpack setup for Node.js targets
Module resolution and aliasing
External dependency management
Custom plugin integration

4. Enhanced Runtime Plugins

Dirname/Filename Plugin (inc/dirname-filename-plugin.ts): Fixes path resolution
Dynamic Import Plugin (inc/dynamic-import-plugin.ts): Enables runtime transpilation
Dynamic Import Helper (inc/dynamic-import-helper.ts): On-demand transpilation logic

5. Caching System (`inc/cache.ts`)

MD5-based file change detection
Intelligent cache invalidation
Performance optimization

6. Parameter Management (`inc/params.ts`)

CLI argument parsing
Configuration management
Environment setup

7. External Dependencies (`inc/inception_externals.ts`)

Smart external module handling
Webpack-related package exclusion
Node.js built-in module management

Compilation Process

Parameter Parsing: Extract and validate CLI arguments and options
Cache Check: Determine if recompilation is necessary using MD5 checksums
Webpack Configuration: Generate optimized webpack configuration with custom plugins
Compilation: Execute webpack build with TypeScript processing and runtime enhancements
Asset Generation: Create optimized JavaScript bundles with proper path handling
Execution: Run the transpiled binary with original parameters

Advanced Features

Path Mapping Support

The package supports TypeScript path mapping for module resolution:

await transpile({
    runspaceDir: '/project',
    tsPaths: {
        '@components/*': ['src/components/*'],
        '@utils/*': ['src/utils/*'],
        '@types/*': ['src/types/*']
    }
});

External Module Handling

Automatically handles external dependencies:

Node.js built-in modules (fs, path, crypto, etc.)
Webpack-related packages
Framework-specific modules (@nestjs/*, etc.)
MongoDB and database drivers

Development vs Production

// Development mode - includes source maps and debugging info
await transpile({
    runspaceDir: '/project',
    isDev: true
});

// Production mode - optimized for performance
await transpile({
    runspaceDir: '/project',
    isDev: false
});