@git.zone/tsbuild

A flexible TypeScript compiler that leverages the latest TypeScript features to streamline your build process.

Install

Add @git.zone/tsbuild to your project using npm or yarn:

npm install @git.zone/tsbuild

or

yarn add @git.zone/tsbuild

Key Features

• Utilize the latest TypeScript features
• Flexible API for customized compilation processes
• Intuitive CLI for common build tasks
• Support for glob patterns to easily target files
• Ordered compilation to respect module dependencies

API Reference

Core Compilation Functions

compileFileArray(fileStringArrayArg: string[], compilerOptionsArg?: CompilerOptions, argvArg?: any): Promise<any[]>

Compiles an array of TypeScript files with customizable compiler options.

import { compileFileArray } from '@git.zone/tsbuild';

const files = [
  './src/file1.ts',
  './src/file2.ts',
];
const options = {
  target: "ES2020",
  module: "CommonJS"
};

compileFileArray(files, options)
  .then(compiledFiles => {
    console.log('Compiled Files:', compiledFiles);
  })
  .catch(error => {
    console.error('Compilation Error:', error);
  });

compileGlobStringObject(globStringObjectArg: Record<string, string>, tsOptionsArg?: CompilerOptions, cwdArg?: string, argvArg?: any): Promise<any[]>

Compiles files matching glob patterns to specified output directories.

import { compileGlobStringObject } from '@git.zone/tsbuild';

const globPattern = {
  './src/**/*.ts': './dist',
};
const compilerOptions = {
  target: "ESNext",
  module: "ESNext",
};

compileGlobStringObject(globPattern, compilerOptions)
  .then(compiledFiles => {
    console.log('Compilation complete:', compiledFiles);
  })
  .catch(error => {
    console.error('Error during compilation:', error);
  });

Command Line Interface

The CLI provides convenient commands for common compilation tasks.

Standard Command

Compiles all TypeScript files in the ts/ directory to the dist_ts directory:

npx tsbuild

Custom Command

Compile specific directories to corresponding dist_ directories:

npx tsbuild custom <Dir1> <Dir2> ...

Example: npx tsbuild custom src utils compiles:

• ./src/**/*.ts → ./dist_src
• ./utils/**/*.ts → ./dist_utils

TSFolders Command

Compiles TypeScript folders in a specific order based on dependencies:

npx tsbuild tsfolders

This command:

1. Identifies all folders starting with ts in the current directory
2. Prioritizes ts_interfaces and ts_shared to be compiled first
3. Orders other folders based on the order property in their tspublish.json files (if available)
4. Compiles each folder to its corresponding dist_ folder

Example compilation order output:

compiling in this order:
[ 'ts_interfaces', 'ts_shared', 'ts_core', 'ts_utils', 'ts_modules' ]

EmitCheck Command

Checks if TypeScript files can be emitted without actually emitting them:

npx tsbuild emitcheck <file_or_glob_pattern> [additional_patterns ...]

This command:

1. Performs type checking on the specified TypeScript file(s)
2. Supports both direct file paths and glob patterns
3. Reports any errors that would prevent successful compilation
4. Exits with code 0 if all files can be emitted, or 1 if any cannot
5. Doesn't produce any output files

Example usage with specific files:

npx tsbuild emitcheck src/main.ts src/utils.ts

Example usage with glob patterns:

npx tsbuild emitcheck "src/**/*.ts" "test/**/*.ts"

Compiler Options

Additional flags can be passed to any command to modify the compilation behavior:

• --skiplibcheck: Skip type checking of declaration files (shows warning)
• --allowimplicitany: Allow variables to be implicitly typed as any
• --commonjs: Use CommonJS module format instead of ESNext

Example:

npx tsbuild --skiplibcheck --allowimplicitany

Default Compiler Options

By default, @git.zone/tsbuild uses the following compiler options:

{
  declaration: true,
  emitDecoratorMetadata: true,
  experimentalDecorators: true,
  inlineSourceMap: true,
  noEmitOnError: true,
  outDir: 'dist_ts/',
  module: ModuleKind.NodeNext,
  target: ScriptTarget.ESNext,
  moduleResolution: ModuleResolutionKind.NodeNext,
  lib: ['lib.dom.d.ts', 'lib.es2022.d.ts'],
  noImplicitAny: true,
  esModuleInterop: true,
  useDefineForClassFields: false,
  verbatimModuleSyntax: true,
  baseUrl: './',
}

These options can be overridden by providing a custom CompilerOptions object.

Path Resolution

The package automatically detects and applies path mappings from your tsconfig.json. When it finds path mappings, it adjusts them to work with the compiled output by replacing ./ts_ with ./dist_ts_ in path aliases.

Notes and Best Practices

• Each glob pattern compilation runs in its own pass, which may cause duplicate error messages if shared files are included in multiple patterns
• Use the --skiplibcheck option cautiously as it will pause for 5 seconds with a warning before continuing
• If you need different output configurations for different file sets, use multiple calls to compileGlobStringObject

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

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.

Trademarks

This 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.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By 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.