Build Management

Build artifact management and cleanup functionality for TypeScript projects using gts.

Capabilities

Clean Function

Remove build output files based on TypeScript configuration.

/**
 * Remove files generated by the build process
 * @param options - Configuration options including target directory
 * @returns Promise resolving to true on successful cleanup, false on error
 */
function clean(options: Options): Promise<boolean>;

Usage Example:

import { clean } from "gts/build/src/clean";
import { Options } from "gts/build/src/cli";

const options: Options = {
  dryRun: false,
  gtsRootDir: "/path/to/gts",
  targetRootDir: process.cwd(),
  yes: false,
  no: false,
  logger: console,
};

const success = await clean(options);
if (success) {
  console.log("Build artifacts cleaned successfully");
} else {
  console.error("Clean operation failed");
}

CLI Usage

# Clean build artifacts
gts clean

# Preview cleanup without deleting (dry run)
gts clean --dry-run

Cleanup Process

The clean function performs the following steps:

1. Read tsconfig.json: Loads TypeScript configuration from the target directory
2. Validate outDir: Ensures compilerOptions.outDir is defined and not "."
3. Safety Check: Prevents deletion of source files by rejecting "." as outDir
4. Remove Directory: Recursively deletes the build output directory

Configuration Requirements

The clean operation requires a valid tsconfig.json file with:

{
  "compilerOptions": {
    "outDir": "build"  // Must be defined and not "."
  }
}

TypeScript Configuration Integration

The clean function integrates with TypeScript's configuration system:

interface TSConfig {
  compilerOptions: ts.CompilerOptions;
}

The function uses TypeScript's CompilerOptions interface to read the outDir setting, ensuring compatibility with all valid TypeScript configurations.

Error Handling

The clean function handles several error conditions:

Missing outDir Configuration

If compilerOptions.outDir is not defined in tsconfig.json:

ERROR: The clean command requires compilerOptions.outDir to be defined in tsconfig.json.

Invalid outDir Value

If outDir is set to "." (current directory):

ERROR: compilerOptions.outDir cannot use the value ".". That would delete all of our sources.

File System Errors

File system errors during directory removal are propagated as exceptions.

Example with error handling:

import { clean } from "gts/build/src/clean";

try {
  const success = await clean(options);
  if (!success) {
    console.error("Clean failed - check tsconfig.json configuration");
    process.exit(1);
  }
} catch (error) {
  console.error("System error during cleanup:", error.message);
  process.exit(1);
}

Integration with TypeScript Compiler

The clean function respects TypeScript's configuration hierarchy:

• Supports extends configuration inheritance
• Resolves relative paths correctly
• Uses the same configuration resolution as the TypeScript compiler
• Compatible with all TypeScript project structures

Safety Features

Several safety features prevent accidental data loss:

1. Source Protection: Prevents deletion when outDir is "."
2. Configuration Validation: Requires explicit outDir configuration
3. Dry Run Support: Preview mode shows what would be deleted
4. Error Recovery: Clear error messages for configuration issues

Directory Structure Example

Typical project structure before and after cleaning:

Before cleaning:

project/
├── src/
│   └── index.ts
├── build/           # Generated by TypeScript compiler
│   ├── src/
│   │   └── index.js
│   └── test/
│       └── test.js
├── tsconfig.json
└── package.json

After cleaning:

project/
├── src/
│   └── index.ts     # Source files preserved
├── tsconfig.json
└── package.json

Performance Considerations

The clean operation:

• Uses rimraf for efficient recursive directory removal
• Operates asynchronously to avoid blocking
• Provides progress feedback through the logger interface
• Handles large build directories efficiently

Integration with Build Scripts

Commonly used in npm scripts for development workflows:

{
  "scripts": {
    "clean": "gts clean",
    "build": "npm run clean && tsc",
    "rebuild": "npm run clean && npm run compile"
  }
}