feat(config): add smartconfig metadata and update TypeScript build configuration docs
This commit is contained in:
@@ -30,8 +30,5 @@
|
||||
},
|
||||
"@git.zone/tsdoc": {
|
||||
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
|
||||
},
|
||||
"@ship.zone/szci": {
|
||||
"npmGlobalTools": []
|
||||
}
|
||||
}
|
||||
10
changelog.md
10
changelog.md
@@ -1,5 +1,15 @@
|
||||
# Changelog
|
||||
|
||||
## 2026-03-24 - 4.4.0 - feat(config)
|
||||
add smartconfig metadata and update TypeScript build configuration docs
|
||||
|
||||
- replace npmextra.json with .smartconfig.json and include it in published files
|
||||
- add a repository license file
|
||||
- upgrade TypeScript and related build dependencies
|
||||
- refine tsconfig path handling to avoid mutating source path mappings
|
||||
- fix tspublish config caching to distinguish unloaded and missing states
|
||||
- expand documentation for import path rewriting, structured logging, and the compilation pipeline
|
||||
|
||||
## 2026-03-06 - 4.3.0 - feat(mod_logger)
|
||||
add centralized TsBuildLogger and replace ad-hoc console output with structured, colored logging
|
||||
|
||||
|
||||
21
license
Normal file
21
license
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024 Task Venture Capital GmbH
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
12
package.json
12
package.json
@@ -36,21 +36,21 @@
|
||||
},
|
||||
"homepage": "https://code.foss.global/git.zone/tsbuild#README",
|
||||
"dependencies": {
|
||||
"@git.zone/tspublish": "^1.11.2",
|
||||
"@git.zone/tspublish": "^1.11.3",
|
||||
"@push.rocks/early": "^4.0.4",
|
||||
"@push.rocks/smartcli": "^4.0.20",
|
||||
"@push.rocks/smartdelay": "^3.0.5",
|
||||
"@push.rocks/smartfile": "^13.1.2",
|
||||
"@push.rocks/smartfs": "^1.3.2",
|
||||
"@push.rocks/smartfs": "^1.5.0",
|
||||
"@push.rocks/smartlog": "^3.2.1",
|
||||
"@push.rocks/smartpath": "^6.0.0",
|
||||
"@push.rocks/smartpromise": "^4.2.3",
|
||||
"typescript": "5.9.3"
|
||||
"typescript": "^6.0.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@git.zone/tsrun": "^2.0.1",
|
||||
"@git.zone/tstest": "^3.2.0",
|
||||
"@types/node": "^25.3.3"
|
||||
"@git.zone/tstest": "^3.5.1",
|
||||
"@types/node": "^25.5.0"
|
||||
},
|
||||
"files": [
|
||||
"ts/**/*",
|
||||
@@ -61,7 +61,7 @@
|
||||
"dist_ts_web/**/*",
|
||||
"assets/**/*",
|
||||
"cli.js",
|
||||
"npmextra.json",
|
||||
".smartconfig.json",
|
||||
"readme.md"
|
||||
],
|
||||
"browserslist": [
|
||||
|
||||
2900
pnpm-lock.yaml
generated
2900
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
@@ -7,11 +7,13 @@
|
||||
2. **TsConfig** - TypeScript configuration management (tsconfig.json handling)
|
||||
3. **TsPublishConfig** - TsPublish configuration (tspublish.json handling)
|
||||
4. **TsUnpacker** - Output directory flattening
|
||||
5. **FsHelpers** - Filesystem utilities (static methods)
|
||||
6. **TsBuildCli** - CLI command handler
|
||||
5. **TsPathRewriter** - Cross-module import path rewriting in compiled output
|
||||
6. **FsHelpers** - Filesystem utilities (static methods)
|
||||
7. **TsBuildLogger** - Centralized structured console output (4-level hierarchy)
|
||||
8. **TsBuildCli** - CLI command handler
|
||||
|
||||
### CLI Commands (5)
|
||||
1. **tsbuild** (default) - Compiles ./ts/**/*.ts → ./dist_ts/
|
||||
1. **tsbuild** (default) - Compiles ./ts/**/*.ts -> ./dist_ts/
|
||||
2. **tsbuild custom <dir1> <dir2>** - Custom directory compilation
|
||||
3. **tsbuild tsfolders** - Auto-discover ts_* folders, compile in order
|
||||
4. **tsbuild emitcheck <pattern>** - Validate emit without output
|
||||
@@ -32,6 +34,7 @@
|
||||
ts/
|
||||
index.ts # Main entry, re-exports all modules
|
||||
plugins.ts # Dependency imports only
|
||||
00_commitinfo_data.ts # Commit info data
|
||||
|
||||
mod_fs/
|
||||
index.ts # exports
|
||||
@@ -46,9 +49,17 @@ ts/
|
||||
index.ts # exports
|
||||
classes.tsunpacker.ts # TsUnpacker - output flattening
|
||||
|
||||
mod_pathrewrite/
|
||||
index.ts # exports
|
||||
classes.tspathrewriter.ts # TsPathRewriter - import path rewriting
|
||||
|
||||
mod_logger/
|
||||
index.ts # exports
|
||||
classes.logger.ts # TsBuildLogger - structured console output
|
||||
|
||||
mod_compiler/
|
||||
index.ts # exports
|
||||
classes.tscompiler.ts # TsCompiler + legacy compatibility functions
|
||||
classes.tscompiler.ts # TsCompiler - main compilation engine
|
||||
|
||||
mod_cli/
|
||||
index.ts # exports
|
||||
@@ -62,6 +73,7 @@ ts/
|
||||
- Type checking with `checkTypes()`, `checkEmit()`
|
||||
- Configuration via TsConfig
|
||||
- Automatic unpacking via TsUnpacker
|
||||
- Import path rewriting via TsPathRewriter (in compileGlob)
|
||||
|
||||
**TsConfig** (`mod_config/classes.tsconfig.ts`)
|
||||
- Load and parse tsconfig.json
|
||||
@@ -78,8 +90,18 @@ ts/
|
||||
- Flatten output directories
|
||||
- Configurable via TsPublishConfig
|
||||
|
||||
**TsPathRewriter** (`mod_pathrewrite/classes.tspathrewriter.ts`)
|
||||
- Auto-detect ts_* folders in project
|
||||
- Rewrite ES module imports, dynamic imports, and require() calls
|
||||
- Transforms `../ts_*` references to `../dist_ts_*` in compiled output
|
||||
|
||||
**TsBuildLogger** (`mod_logger/classes.logger.ts`)
|
||||
- 4-level visual hierarchy: HEADER, STEP, DETAIL, SUCCESS/ERROR/WARN
|
||||
- ANSI color output
|
||||
- Static methods (no instantiation needed)
|
||||
|
||||
**FsHelpers** (`mod_fs/classes.fshelpers.ts`)
|
||||
- `listFilesWithGlob()` - Glob pattern file listing
|
||||
- `listFilesWithGlob()` - Glob pattern file listing via smartfs
|
||||
- `extractSourceFolder()` - Pattern parsing
|
||||
- File/directory existence checks
|
||||
- Directory operations
|
||||
@@ -103,8 +125,8 @@ Cannot be overridden by tsconfig.json alone:
|
||||
- `inlineSourceMap: true` - Debugging
|
||||
|
||||
### Path Transformation
|
||||
- Automatic: `./ts_interfaces` → `./dist_ts_interfaces`
|
||||
- In tsconfig paths: `./ts_*` → `./dist_ts_*` (first array element only)
|
||||
- Automatic: `./ts_interfaces` -> `./dist_ts_interfaces`
|
||||
- In tsconfig paths: `./ts_*` -> `./dist_ts_*` (first array element only)
|
||||
|
||||
## Default Compiler Options
|
||||
- Module: NodeNext (ESM with CommonJS fallback)
|
||||
@@ -137,14 +159,16 @@ interface ICompileResult {
|
||||
```
|
||||
|
||||
## Dependencies Used
|
||||
- @git.zone/tspublish@^1.10.3 - Module ordering
|
||||
- @push.rocks/smartcli@^4.0.19 - CLI framework
|
||||
- @git.zone/tspublish@^1.11.3 - Module ordering
|
||||
- @push.rocks/early@^4.0.4 - Early initialization
|
||||
- @push.rocks/smartcli@^4.0.20 - CLI framework
|
||||
- @push.rocks/smartdelay@^3.0.5 - Delay utilities
|
||||
- @push.rocks/smartfile@^13.1.2 - File content handling
|
||||
- @push.rocks/smartfs@^1.2.0 - Filesystem operations
|
||||
- @push.rocks/smartfs@^1.5.0 - Filesystem operations
|
||||
- @push.rocks/smartlog@^3.2.1 - Logging
|
||||
- @push.rocks/smartpath@^6.0.0 - Path transformation utilities
|
||||
- @push.rocks/smartpromise@^4.2.3 - Promise utilities
|
||||
- @push.rocks/smartdelay@^3.0.5 - Delay utilities
|
||||
- typescript@5.9.3 - TypeScript compiler
|
||||
- typescript@^6.0.2 - TypeScript compiler
|
||||
|
||||
### smartfs Usage
|
||||
- File listing: `smartfs.directory(path).recursive().filter(pattern).list()`
|
||||
@@ -152,29 +176,32 @@ interface ICompileResult {
|
||||
- Directory existence: `smartfs.directory(path).exists()`
|
||||
- FsHelpers wraps smartfs for glob pattern support
|
||||
|
||||
## Compilation Pipeline (compileGlob)
|
||||
|
||||
1. **Phase 1: Resolve & Clean** - Resolve glob patterns, list files, clear all output dirs
|
||||
2. **Phase 2: Compile** - Compile each task sequentially with error tracking
|
||||
3. **Phase 3: Unpack** - Flatten nested output directories for successful compilations
|
||||
4. **Phase 4: Path Rewrite** - Rewrite cross-module import paths in output dirs
|
||||
|
||||
## Unpack Feature
|
||||
|
||||
When TypeScript compiles files that import from sibling directories, it creates nested output:
|
||||
```
|
||||
dist_ts_core/
|
||||
ts_core/ ← nested output
|
||||
ts_shared/ ← pulled-in dependency
|
||||
ts_core/ <- nested output
|
||||
ts_shared/ <- pulled-in dependency
|
||||
```
|
||||
|
||||
The unpack feature automatically flattens this to:
|
||||
```
|
||||
dist_ts_core/
|
||||
index.js ← flat
|
||||
index.js <- flat
|
||||
```
|
||||
|
||||
### Configuration
|
||||
- Reads `tspublish.json` from source folder
|
||||
- `unpack: true` (default if not present) → flatten output
|
||||
- `unpack: false` → skip unpacking
|
||||
|
||||
### Implementation
|
||||
- `TsUnpacker` class in `mod_unpack/classes.tsunpacker.ts`
|
||||
- Called automatically after each successful compilation in `TsCompiler.compileGlob()`
|
||||
- `unpack: true` (default if not present) -> flatten output
|
||||
- `unpack: false` -> skip unpacking
|
||||
|
||||
## Special Behaviors
|
||||
|
||||
@@ -206,10 +233,4 @@ Two-phase check:
|
||||
- Protected options ensure integrity
|
||||
- Pre-emit checks before emit phase
|
||||
- CLI exit code handling (0=success, 1=error)
|
||||
|
||||
## Recent Changes
|
||||
- 3.1.4+ - Major restructuring with mod_* modules
|
||||
- Full OO architecture with TsCompiler, TsConfig, TsPublishConfig, TsUnpacker, TsBuildCli, FsHelpers
|
||||
- Backward compatibility maintained for legacy functions
|
||||
- Automatic "unpack" feature for nested output directories
|
||||
- Migrated filesystem operations from smartfile to smartfs
|
||||
- Event loop yield after emit for XFS filesystem reliability
|
||||
|
||||
189
readme.md
189
readme.md
@@ -1,12 +1,12 @@
|
||||
# @git.zone/tsbuild
|
||||
|
||||
A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, and automatic output directory management. 🚀
|
||||
A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, automatic output directory management, and cross-module import path rewriting.
|
||||
|
||||
## Issue Reporting and Security
|
||||
|
||||
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
||||
|
||||
## 📦 Install
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# Using pnpm (recommended)
|
||||
@@ -16,22 +16,23 @@ pnpm install @git.zone/tsbuild --save-dev
|
||||
npm install @git.zone/tsbuild --save-dev
|
||||
```
|
||||
|
||||
## ⚡ Why tsbuild?
|
||||
## Why tsbuild?
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| 🔧 **Smart tsconfig.json Integration** | Respects all your compiler options with intelligent merging |
|
||||
| 🛡️ **Protected Defaults** | Critical build settings are safeguarded while staying flexible |
|
||||
| 🎯 **Zero Config** | Works perfectly without tsconfig.json |
|
||||
| 🌐 **Glob Pattern Support** | Compile multiple directories with a single command |
|
||||
| 📊 **Dependency-Aware** | Automatically orders compilation based on module dependencies |
|
||||
| ✅ **Type Checking** | Validate code without emitting files |
|
||||
| 🧹 **Clean Builds** | Automatically clears output directories before compilation |
|
||||
| 📁 **Auto-Unpack** | Flattens nested output directories automatically |
|
||||
| 🔄 **CI/CD Ready** | JSON output mode and proper exit codes |
|
||||
| ✨ **Modern Defaults** | ESNext, NodeNext modules, decorators out of the box |
|
||||
| **Smart tsconfig.json Integration** | Respects all your compiler options with intelligent merging |
|
||||
| **Protected Defaults** | Critical build settings are safeguarded while staying flexible |
|
||||
| **Zero Config** | Works perfectly without tsconfig.json |
|
||||
| **Glob Pattern Support** | Compile multiple directories with a single command |
|
||||
| **Dependency-Aware** | Automatically orders compilation based on module dependencies |
|
||||
| **Type Checking** | Validate code without emitting files |
|
||||
| **Clean Builds** | Automatically clears output directories before compilation |
|
||||
| **Auto-Unpack** | Flattens nested output directories automatically |
|
||||
| **Import Path Rewriting** | Rewrites cross-module imports to point at compiled output |
|
||||
| **CI/CD Ready** | JSON output mode and proper exit codes |
|
||||
| **Modern Defaults** | ESNext, NodeNext modules, decorators out of the box |
|
||||
|
||||
## 🚀 Quick Start
|
||||
## Quick Start
|
||||
|
||||
### CLI Usage
|
||||
|
||||
@@ -46,8 +47,8 @@ Compiles `./ts/**/*.ts` to `./dist_ts/`
|
||||
npx tsbuild custom src utils
|
||||
```
|
||||
Compiles:
|
||||
- `./src/**/*.ts` → `./dist_src/`
|
||||
- `./utils/**/*.ts` → `./dist_utils/`
|
||||
- `./src/**/*.ts` -> `./dist_src/`
|
||||
- `./utils/**/*.ts` -> `./dist_utils/`
|
||||
|
||||
**Auto-discover and compile in dependency order:**
|
||||
```bash
|
||||
@@ -97,7 +98,7 @@ await compiler.compileGlob({
|
||||
});
|
||||
```
|
||||
|
||||
## 🛠️ CLI Commands
|
||||
## CLI Commands
|
||||
|
||||
### 1. Default Build
|
||||
|
||||
@@ -149,7 +150,7 @@ npx tsbuild custom src utils
|
||||
npx tsbuild custom api models services --commonjs
|
||||
```
|
||||
|
||||
### 3. TSFolders (Dependency-Aware) 📊
|
||||
### 3. TSFolders (Dependency-Aware)
|
||||
|
||||
```bash
|
||||
npx tsbuild tsfolders [options]
|
||||
@@ -165,14 +166,14 @@ Automatically discovers and compiles all `ts_*` folders in dependency order:
|
||||
**Example output:**
|
||||
```
|
||||
TypeScript Folder Compilation Plan (5 folders)
|
||||
1/5 ts_interfaces
|
||||
2/5 ts_shared
|
||||
3/5 ts_core
|
||||
4/5 ts_utils
|
||||
5/5 ts_modules
|
||||
1. ts_interfaces
|
||||
2. ts_shared
|
||||
3. ts_core
|
||||
4. ts_utils
|
||||
5. ts_modules
|
||||
```
|
||||
|
||||
### 4. Emit Check ✓
|
||||
### 4. Emit Check
|
||||
|
||||
```bash
|
||||
npx tsbuild emitcheck <file_or_pattern> [more...] [options]
|
||||
@@ -192,7 +193,7 @@ npx tsbuild emitcheck "src/**/*.ts" "test/**/*.ts"
|
||||
- `0` - All files can be emitted
|
||||
- `1` - One or more files have errors
|
||||
|
||||
### 5. Type Check 🔍
|
||||
### 5. Type Check
|
||||
|
||||
```bash
|
||||
npx tsbuild check [pattern] [more...] [options]
|
||||
@@ -218,7 +219,7 @@ npx tsbuild check
|
||||
# All default type checks passed!
|
||||
```
|
||||
|
||||
## 📖 API Reference
|
||||
## API Reference
|
||||
|
||||
### TsCompiler Class
|
||||
|
||||
@@ -285,7 +286,7 @@ try {
|
||||
|
||||
#### compileGlob(globPatterns, customOptions?)
|
||||
|
||||
Compile multiple glob patterns to different destinations. Automatically clears output directories before compilation and unpacks nested output.
|
||||
Compile multiple glob patterns to different destinations. Automatically clears output directories before compilation, unpacks nested output, and rewrites cross-module import paths.
|
||||
|
||||
```typescript
|
||||
const result = await compiler.compileGlob({
|
||||
@@ -367,10 +368,28 @@ Flattens nested TypeScript output directories.
|
||||
```typescript
|
||||
import { TsUnpacker } from '@git.zone/tsbuild';
|
||||
|
||||
const unpacker = new TsUnpacker('./dist_ts', './ts');
|
||||
const unpacker = new TsUnpacker('ts_core', './dist_ts_core');
|
||||
await unpacker.unpack();
|
||||
```
|
||||
|
||||
#### TsPathRewriter
|
||||
|
||||
Rewrites cross-module import paths in compiled output files. When TypeScript compiles files that import from sibling directories (e.g., `../ts_shared/helper.js`), TsPathRewriter rewrites those paths to reference the compiled output directories (`../dist_ts_shared/helper.js`).
|
||||
|
||||
```typescript
|
||||
import { TsPathRewriter } from '@git.zone/tsbuild';
|
||||
|
||||
// Auto-detect all ts_* folders in the project
|
||||
const rewriter = await TsPathRewriter.fromProjectDirectory(process.cwd());
|
||||
const filesModified = await rewriter.rewriteDirectory('./dist_ts_core');
|
||||
|
||||
// Or from explicit glob patterns
|
||||
const rewriter2 = TsPathRewriter.fromGlobPatterns({
|
||||
'./ts_core/**/*.ts': './dist_ts_core',
|
||||
'./ts_shared/**/*.ts': './dist_ts_shared',
|
||||
});
|
||||
```
|
||||
|
||||
#### FsHelpers
|
||||
|
||||
Static filesystem utilities.
|
||||
@@ -398,7 +417,7 @@ const cli = new TsBuildCli('/path/to/project');
|
||||
cli.run();
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
## Configuration
|
||||
|
||||
### tsconfig.json Support
|
||||
|
||||
@@ -419,19 +438,19 @@ tsbuild fully supports all compiler options from `tsconfig.json`. Your project c
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Priority (5 Levels) 📋
|
||||
### Configuration Priority (5 Levels)
|
||||
|
||||
When multiple configuration sources exist, they merge in this order (later overrides earlier):
|
||||
|
||||
| Priority | Source | Description |
|
||||
|----------|--------|-------------|
|
||||
| 1️⃣ | **Default Options** | tsbuild's sensible defaults |
|
||||
| 2️⃣ | **tsconfig.json** | All options from your tsconfig.json (if present) |
|
||||
| 3️⃣ | **Protected Defaults** | Critical options for build integrity |
|
||||
| 4️⃣ | **Programmatic Options** | Options passed to API functions |
|
||||
| 5️⃣ | **CLI Flags** | Command-line arguments (highest priority) |
|
||||
| 1 | **Default Options** | tsbuild's sensible defaults |
|
||||
| 2 | **tsconfig.json** | All options from your tsconfig.json (if present) |
|
||||
| 3 | **Protected Defaults** | Critical options for build integrity |
|
||||
| 4 | **Programmatic Options** | Options passed to API functions |
|
||||
| 5 | **CLI Flags** | Command-line arguments (highest priority) |
|
||||
|
||||
### Protected Options 🛡️
|
||||
### Protected Options
|
||||
|
||||
These options cannot be overridden by tsconfig.json alone (but can be overridden programmatically or via CLI):
|
||||
|
||||
@@ -449,8 +468,6 @@ When no tsconfig.json exists:
|
||||
```typescript
|
||||
{
|
||||
declaration: true, // Generate .d.ts files
|
||||
emitDecoratorMetadata: true, // Support DI frameworks
|
||||
experimentalDecorators: true, // Enable decorators
|
||||
inlineSourceMap: true, // Debug-friendly
|
||||
noEmitOnError: true, // Fail-fast on errors
|
||||
outDir: 'dist_ts/', // Output directory
|
||||
@@ -463,7 +480,7 @@ When no tsconfig.json exists:
|
||||
}
|
||||
```
|
||||
|
||||
### Path Transformation 🔄
|
||||
### Path Transformation
|
||||
|
||||
tsbuild automatically transforms path mappings:
|
||||
|
||||
@@ -480,12 +497,12 @@ tsbuild automatically transforms path mappings:
|
||||
|
||||
**Automatic transformation:**
|
||||
```
|
||||
./ts_models/* → ./dist_ts_models/*
|
||||
./ts_models/* -> ./dist_ts_models/*
|
||||
```
|
||||
|
||||
## ✨ Features
|
||||
## Features
|
||||
|
||||
### Clean Builds 🧹
|
||||
### Clean Builds
|
||||
|
||||
Output directories are automatically cleared before compilation:
|
||||
|
||||
@@ -496,7 +513,23 @@ Compiling 14 files from ./ts/**/*.ts
|
||||
|
||||
This ensures no stale files remain from previous builds.
|
||||
|
||||
### Monorepo Support with tspublish 📦
|
||||
### Import Path Rewriting
|
||||
|
||||
When working with multi-module projects (multiple `ts_*` folders), TypeScript compiles import paths relative to source directories. After compilation and unpacking, these paths would be wrong because the directory structure changes.
|
||||
|
||||
tsbuild automatically detects all `ts_*` folders in the project and rewrites import paths in the compiled output:
|
||||
|
||||
```
|
||||
# Source code
|
||||
import { helper } from '../ts_shared/helper.js';
|
||||
|
||||
# Compiled output (after rewriting)
|
||||
import { helper } from '../dist_ts_shared/helper.js';
|
||||
```
|
||||
|
||||
This works for ES module imports, dynamic `import()` calls, and CommonJS `require()` statements. The rewriting happens automatically as part of `compileGlob()`.
|
||||
|
||||
### Monorepo Support with tspublish
|
||||
|
||||
tsbuild is designed to work seamlessly with [@git.zone/tspublish](https://code.foss.global/git.zone/tspublish) for monorepo workflows. This enables building and publishing multiple packages from a single repository.
|
||||
|
||||
@@ -504,12 +537,12 @@ tsbuild is designed to work seamlessly with [@git.zone/tspublish](https://code.f
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── ts/ # Main package source
|
||||
├── ts_interfaces/ # Shared interfaces (order: 1)
|
||||
├── ts_shared/ # Shared utilities (order: 2)
|
||||
├── ts_core/ # Core logic (order: 3)
|
||||
├── ts_web/ # Web-specific code (order: 4)
|
||||
└── ts_node/ # Node-specific code (order: 5)
|
||||
ts/ # Main package source
|
||||
ts_interfaces/ # Shared interfaces (order: 1)
|
||||
ts_shared/ # Shared utilities (order: 2)
|
||||
ts_core/ # Core logic (order: 3)
|
||||
ts_web/ # Web-specific code (order: 4)
|
||||
ts_node/ # Node-specific code (order: 5)
|
||||
```
|
||||
|
||||
Each `ts_*` folder can contain its own `tspublish.json` to configure compilation and publishing behavior.
|
||||
@@ -529,10 +562,10 @@ Create a `tspublish.json` in each `ts_*` folder:
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `name` | string | — | Package name for publishing |
|
||||
| `name` | string | -- | Package name for publishing |
|
||||
| `order` | number | `Infinity` | Build sequence (lower builds first) |
|
||||
| `unpack` | boolean | `true` | Flatten nested output directories |
|
||||
| `dependencies` | string[] | — | Monorepo dependencies to bundle |
|
||||
| `dependencies` | string[] | -- | Monorepo dependencies to bundle |
|
||||
|
||||
#### Build Order
|
||||
|
||||
@@ -548,31 +581,21 @@ npx tsbuild tsfolders
|
||||
3. Other folders sorted by `order` property
|
||||
4. Folders without `order` are built last
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
TypeScript Folder Compilation Plan (5 folders)
|
||||
1/5 ts_interfaces (order: 1)
|
||||
2/5 ts_shared (order: 2)
|
||||
3/5 ts_core (order: 3)
|
||||
4/5 ts_web (order: 4)
|
||||
5/5 ts_node (order: 5)
|
||||
```
|
||||
|
||||
### Auto-Unpack 📁
|
||||
### Auto-Unpack
|
||||
|
||||
When TypeScript compiles files that import from sibling directories, it creates nested output:
|
||||
|
||||
```
|
||||
dist_ts_core/
|
||||
ts_core/ ← nested output
|
||||
ts_shared/ ← pulled-in dependency
|
||||
ts_core/ <-- nested output
|
||||
ts_shared/ <-- pulled-in dependency
|
||||
```
|
||||
|
||||
tsbuild automatically flattens this to:
|
||||
|
||||
```
|
||||
dist_ts_core/
|
||||
index.js ← flat, clean structure
|
||||
index.js <-- flat, clean structure
|
||||
```
|
||||
|
||||
This is especially important for monorepos where packages import from each other.
|
||||
@@ -591,11 +614,11 @@ This is especially important for monorepos where packages import from each other
|
||||
- The source folder's contents (`ts_core/`) are moved to the root of `dist_ts_core/`
|
||||
- Sibling folders (`ts_shared/`) that were pulled in are removed (they have their own dist)
|
||||
|
||||
### Decorator Support 🎨
|
||||
### Decorator Support
|
||||
|
||||
tsbuild supports both **TC39 standard decorators** (recommended) and legacy experimental decorators.
|
||||
|
||||
**TC39 Standard Decorators (Preferred)** 🌟
|
||||
**TC39 Standard Decorators (Preferred)**
|
||||
|
||||
We strongly recommend using TC39 standard decorators for all new code. They are the official JavaScript standard and provide better semantics:
|
||||
|
||||
@@ -618,19 +641,8 @@ class UserService {
|
||||
|
||||
**Legacy Decorators (Backwards Compatibility)**
|
||||
|
||||
For existing projects using frameworks like NestJS, TypeORM, or Angular that still require experimental decorators:
|
||||
For existing projects using frameworks that still require experimental decorators:
|
||||
|
||||
```typescript
|
||||
@Injectable()
|
||||
class UserService {
|
||||
constructor(
|
||||
@Inject('CONFIG') private config: Config,
|
||||
private logger: Logger
|
||||
) {}
|
||||
}
|
||||
```
|
||||
|
||||
Enable legacy decorators in your `tsconfig.json`:
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
@@ -640,9 +652,18 @@ Enable legacy decorators in your `tsconfig.json`:
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 **Tip:** When starting new projects or migrating existing ones, prefer TC39 decorators. They're the future of JavaScript and don't require experimental flags.
|
||||
### Structured Logging
|
||||
|
||||
## 🔄 CI/CD Integration
|
||||
tsbuild uses a 4-level visual hierarchy for console output, making it easy to follow compilation progress:
|
||||
|
||||
- **HEADER** - Top-level section start (emoji + bold text + separator)
|
||||
- **STEP** - Major action within a section (emoji + text)
|
||||
- **DETAIL** - Supplementary info under a step (indented)
|
||||
- **SUCCESS/ERROR/WARN** - Outcome indicators with color coding
|
||||
|
||||
All output uses ANSI color codes for terminal readability. Use `--quiet` to suppress output or `--json` for machine-readable format.
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
@@ -657,7 +678,7 @@ jobs:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
node-version: '22'
|
||||
|
||||
- run: npm install
|
||||
- run: npx tsbuild
|
||||
@@ -694,7 +715,7 @@ npx tsbuild --json --quiet
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
@@ -725,7 +746,7 @@ Only use this if you trust your dependencies' type definitions.
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@git.zone/tsbuild',
|
||||
version: '4.3.0',
|
||||
version: '4.4.0',
|
||||
description: 'A tool for compiling TypeScript files using the latest nightly features, offering flexible APIs and a CLI for streamlined development.'
|
||||
}
|
||||
|
||||
@@ -18,7 +18,6 @@ export const compilerOptionsDefault: CompilerOptions = {
|
||||
noImplicitAny: false,
|
||||
esModuleInterop: true,
|
||||
verbatimModuleSyntax: true,
|
||||
baseUrl: './',
|
||||
};
|
||||
|
||||
/**
|
||||
@@ -98,12 +97,13 @@ export class TsConfig {
|
||||
|
||||
// Apply path transformations (ts_ → dist_ts_)
|
||||
if (tsconfig.compilerOptions.paths) {
|
||||
returnObject.paths = { ...tsconfig.compilerOptions.paths };
|
||||
for (const pathKey of Object.keys(returnObject.paths)) {
|
||||
if (Array.isArray(returnObject.paths[pathKey]) && returnObject.paths[pathKey].length > 0) {
|
||||
returnObject.paths[pathKey][0] = returnObject.paths[pathKey][0].replace('./ts_', './dist_ts_');
|
||||
const paths: Record<string, string[]> = { ...tsconfig.compilerOptions.paths };
|
||||
for (const pathKey of Object.keys(paths)) {
|
||||
if (Array.isArray(paths[pathKey]) && paths[pathKey].length > 0) {
|
||||
paths[pathKey][0] = paths[pathKey][0].replace('./ts_', './dist_ts_');
|
||||
}
|
||||
}
|
||||
returnObject.paths = paths;
|
||||
}
|
||||
|
||||
this.cachedTsConfig = returnObject;
|
||||
|
||||
@@ -17,7 +17,8 @@ export interface ITsPublishJson {
|
||||
*/
|
||||
export class TsPublishConfig {
|
||||
private folderPath: string;
|
||||
private cachedConfig: ITsPublishJson | null | undefined = undefined;
|
||||
private cachedConfig: ITsPublishJson | null = null;
|
||||
private cacheLoaded = false;
|
||||
|
||||
constructor(folderPath: string) {
|
||||
this.folderPath = folderPath;
|
||||
@@ -35,7 +36,7 @@ export class TsPublishConfig {
|
||||
* Returns null if file doesn't exist or is invalid
|
||||
*/
|
||||
public async load(): Promise<ITsPublishJson | null> {
|
||||
if (this.cachedConfig !== undefined) {
|
||||
if (this.cacheLoaded) {
|
||||
return this.cachedConfig;
|
||||
}
|
||||
|
||||
@@ -43,9 +44,11 @@ export class TsPublishConfig {
|
||||
const configPath = path.join(this.folderPath, 'tspublish.json');
|
||||
const content = await fs.promises.readFile(configPath, 'utf8');
|
||||
this.cachedConfig = JSON.parse(content);
|
||||
this.cacheLoaded = true;
|
||||
return this.cachedConfig;
|
||||
} catch {
|
||||
this.cachedConfig = null;
|
||||
this.cacheLoaded = true;
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -55,7 +58,7 @@ export class TsPublishConfig {
|
||||
* Returns null if file doesn't exist or is invalid
|
||||
*/
|
||||
public loadSync(): ITsPublishJson | null {
|
||||
if (this.cachedConfig !== undefined) {
|
||||
if (this.cacheLoaded) {
|
||||
return this.cachedConfig;
|
||||
}
|
||||
|
||||
@@ -63,9 +66,11 @@ export class TsPublishConfig {
|
||||
const configPath = path.join(this.folderPath, 'tspublish.json');
|
||||
const content = fs.readFileSync(configPath, 'utf8');
|
||||
this.cachedConfig = JSON.parse(content);
|
||||
this.cacheLoaded = true;
|
||||
return this.cachedConfig;
|
||||
} catch {
|
||||
this.cachedConfig = null;
|
||||
this.cacheLoaded = true;
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -111,6 +116,7 @@ export class TsPublishConfig {
|
||||
* Clear the cached config (useful for reloading)
|
||||
*/
|
||||
public clearCache(): void {
|
||||
this.cachedConfig = undefined;
|
||||
this.cachedConfig = null;
|
||||
this.cacheLoaded = false;
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user