0
# TypeScript Compilation
1

2
TypeScript compiler wrapper providing enhanced functionality for LoopBack 4 projects including ttypescript support, resource copying, and automatic configuration generation.
3

4
## Capabilities
5

6
### lb-tsc / lb-ttsc Command
7

8
Compiles TypeScript files with automatic configuration discovery and enhanced features.
9

10
```typescript { .api }
11
/**
12
 * TypeScript compiler function with enhanced features
13
 * @param argv - Command line arguments including options
14
 * @param options - Execution options for dry run and process control
15
 * @returns ChildProcess when executed, string when dry run
16
 */
17
function tsc(argv: string[], options?: RunOptions): ChildProcess | string;
18
```
19

20
**CLI Usage:**
21

22
```bash
23
# Standard TypeScript compilation
24
lb-tsc
25

26
# Watch mode
27
lb-tsc --watch
28

29
# Custom target and output directory
30
lb-tsc --target es2017 --outDir dist
31

32
# Copy non-TypeScript resources
33
lb-tsc --copy-resources
34

35
# Use ttypescript for plugins
36
lb-ttsc
37
# or
38
lb-tsc --use-ttypescript
39

40
# Custom project file
41
lb-tsc -p tsconfig.build.json
42
```
43

44
**Programmatic Usage:**
45

46
```typescript
47
import { tsc } from "@loopback/build";
48

49
// Compile with default settings
50
const child = tsc(process.argv);
51

52
// Dry run to see command
53
const command = tsc(["--watch"], { dryRun: true });
54
console.log(command); // "node .../tsc --watch"
55

56
// Custom working directory
57
tsc(["--outDir", "build"], { cwd: "/path/to/project" });
58
```
59

60
### TypeScript Configuration Discovery
61

62
Automatically discovers and creates TypeScript configuration files.
63

64
**Configuration Search Order:**
65
1. `tsconfig.build.json` in project root
66
2. `tsconfig.json` in project root  
67
3. Auto-generated `tsconfig.json` extending `@loopback/build/config/tsconfig.common.json`
68

69
**Auto-generated Configuration:**
70

71
```json
72
{
73
  "extends": "@loopback/build/config/tsconfig.common.json",
74
  "compilerOptions": {
75
    "outDir": "dist",
76
    "rootDir": "src"
77
  },
78
  "include": ["src"]
79
}
80
```
81

82
### ttypescript Support
83

84
Optional integration with ttypescript for TypeScript plugin support.
85

86
```typescript { .api }
87
// lb-ttsc automatically uses ttypescript if available
88
// lb-tsc --use-ttypescript flag enables ttypescript
89
```
90

91
**Requirements:** 
92
- `ttypescript` package must be installed
93
- Fails gracefully if ttypescript is not available
94

95
### Resource Copying
96

97
Copies non-TypeScript files from source to output directory.
98

99
```typescript { .api }
100
// --copy-resources flag enables file copying
101
// Copies all non-.ts files from src/ and test/ directories
102
// Preserves relative directory structure
103
```
104

105
**Usage Examples:**
106

107
```bash
108
# Copy resources during compilation
109
lb-tsc --copy-resources
110

111
# Copy resources with custom configuration
112
lb-tsc --copy-resources --outDir build --rootDir src
113
```
114

115
**Copied File Patterns:**
116
- All files in `src/` directory (excluding .ts files)
117
- All files in `test/` directory (excluding .ts files)
118
- Preserves directory structure relative to `rootDir`
119

120
### Composite Project Support
121

122
Supports TypeScript composite projects with `tsc -b` build mode.
123

124
```typescript { .api }
125
// Automatically detects composite projects via tsconfig references
126
// Uses 'tsc -b' for composite project builds
127
// Filters invalid arguments for build mode
128
```
129

130
**Usage:**
131

132
```typescript
133
// tsconfig.json with references
134
{
135
  "references": [
136
    { "path": "./packages/core" },
137
    { "path": "./packages/utils" }
138
  ]
139
}
140
```
141

142
### Advanced Options
143

144
Additional compiler options specific to @loopback/build.
145

146
```typescript { .api }
147
interface CompilerOptions {
148
  "--copy-resources": boolean;  // Copy non-TS files to outDir
149
  "--use-ttypescript": boolean; // Use ttypescript instead of tsc
150
  "--target": string;           // TypeScript compilation target
151
  "--outDir": string;           // Output directory
152
  "-p" | "--project": string;   // Project file path
153
}
154
```
155

156
**Option Processing:**
157
- Custom options are removed before passing to TypeScript compiler
158
- Target and output directory are extracted and handled separately
159
- Project file path is resolved relative to current working directory
160

161
### Default TypeScript Configuration
162

163
Base configuration provided by @loopback/build.
164

165
```typescript { .api }
166
// config/tsconfig.common.json contents:
167
interface TypeScriptConfig {
168
  compilerOptions: {
169
    emitDecoratorMetadata: true;
170
    experimentalDecorators: true;
171
    resolveJsonModule: true;
172
    skipLibCheck: true;
173
    strict: true;
174
    strictPropertyInitialization: false;
175
    useUnknownInCatchVariables: false;
176
    incremental: true;
177
    lib: ["es2020"];
178
    module: "commonjs";
179
    esModuleInterop: true;
180
    moduleResolution: "node";
181
    target: "es2018";
182
    sourceMap: true;
183
    declaration: true;
184
    importHelpers: true;
185
  };
186
}
187
```