0
# Project Management
1

2
Core project functionality for managing TypeScript projects, source files, and compilation settings. The Project class serves as the main entry point for all ts-morph operations.
3

4
## Capabilities
5

6
### Project Class
7

8
The central class for managing TypeScript projects, providing methods for adding source files, managing directories, and performing compilation.
9

10
```typescript { .api }
11
/**
12
 * Main class for managing TypeScript projects
13
 */
14
class Project {
15
  /** Create a new project instance */
16
  constructor(options?: ProjectOptions);
17
  
18
  /** Add an existing source file to the project */
19
  addSourceFileAtPath(filePath: string): SourceFile;
20
  
21
  /** Add an existing source file if it exists, returning undefined if not found */
22
  addSourceFileAtPathIfExists(filePath: string): SourceFile | undefined;
23
  
24
  /** Add multiple source files using glob patterns */
25
  addSourceFilesAtPaths(fileGlobs: string | ReadonlyArray<string>): SourceFile[];
26
  
27
  /** Create a new source file in the project */
28
  createSourceFile(filePath: string, text?: string, options?: SourceFileCreateOptions): SourceFile;
29
  
30
  /** Get a source file by its file name or path */
31
  getSourceFile(fileNameOrPath: string): SourceFile | undefined;
32
  
33
  /** Get a source file using a search function */
34
  getSourceFile(searchFunction: (file: SourceFile) => boolean): SourceFile | undefined;
35
  
36
  /** Get a source file by its file name or path, throwing if not found */
37
  getSourceFileOrThrow(fileNameOrPath: string): SourceFile;
38
  
39
  /** Get a source file using a search function, throwing if not found */
40
  getSourceFileOrThrow(searchFunction: (file: SourceFile) => boolean): SourceFile;
41
  
42
  /** Get all source files in the project */
43
  getSourceFiles(): SourceFile[];
44
  
45
  /** Get source files matching glob pattern(s) */
46
  getSourceFiles(globPatterns: string | ReadonlyArray<string>): SourceFile[];
47
  
48
  /** Add a directory to the project */
49
  addDirectoryAtPath(dirPath: string, options?: DirectoryAddOptions): Directory;
50
  
51
  /** Add a directory if it exists, returning undefined if not found */
52
  addDirectoryAtPathIfExists(dirPath: string, options?: DirectoryAddOptions): Directory | undefined;
53
  
54
  /** Create a directory in the project */
55
  createDirectory(dirPath: string): Directory;
56
  
57
  /** Get a directory by path */
58
  getDirectory(dirPath: string): Directory | undefined;
59
  
60
  /** Get a directory by path, throwing if not found */
61
  getDirectoryOrThrow(dirPath: string): Directory;
62
  
63
  /** Get all directories in the project */
64
  getDirectories(): Directory[];
65
  
66
  /** Save all unsaved source files asynchronously */
67
  save(): Promise<void>;
68
  
69
  /** Save all unsaved source files synchronously */
70
  saveSync(): void;
71
  
72
  /** Emit TypeScript files to JavaScript asynchronously */
73
  emit(): Promise<EmitResult>;
74
  
75
  /** Emit TypeScript files to JavaScript synchronously */
76
  emitSync(): EmitResult;
77
  
78
  /** Get the TypeScript program */
79
  getProgram(): Program;
80
  
81
  /** Get the TypeScript type checker */
82
  getTypeChecker(): TypeChecker;
83
  
84
  /** Get the language service */
85
  getLanguageService(): LanguageService;
86
  
87
  /** Get compiler options */
88
  getCompilerOptions(): CompilerOptions;
89
  
90
  /** Get pre-emit diagnostics for the project */
91
  getPreEmitDiagnostics(): Diagnostic[];
92
  
93
  /** Get configuration file parsing diagnostics */
94
  getConfigFileParsingDiagnostics(): Diagnostic[];
95
}
96

97
interface ProjectOptions {
98
  /** Path to tsconfig.json file */
99
  tsConfigFilePath?: string;
100
  
101
  /** Compiler options to use */
102
  compilerOptions?: CompilerOptions;
103
  
104
  /** Custom file system host */
105
  fileSystem?: FileSystemHost;
106
  
107
  /** Code manipulation settings */
108
  manipulationSettings?: Partial<ManipulationSettings>;
109
  
110
  /** Whether to use in-memory file system */
111
  useInMemoryFileSystem?: boolean;
112
  
113
  /** Whether to skip adding files from tsconfig.json */
114
  skipAddingFilesFromTsConfig?: boolean;
115
  
116
  /** Skip resolving file dependencies when adding files from tsconfig */
117
  skipFileDependencyResolution?: boolean;
118
  
119
  /** Skip loading lib files */
120
  skipLoadingLibFiles?: boolean;
121
  
122
  /** The folder to use for loading lib files */
123
  libFolderPath?: string;
124
  
125
  /** Default compiler options (can be overridden by tsConfigFilePath or compilerOptions) */
126
  defaultCompilerOptions?: CompilerOptions;
127
  
128
  /** Creates a resolution host for custom module/type reference directive resolution */
129
  resolutionHost?: ResolutionHostFactory;
130
}
131

132
interface SourceFileCreateOptions {
133
  /** Whether to overwrite if file exists */
134
  overwrite?: boolean;
135
  
136
  /** Specifies the script kind of the source file */
137
  scriptKind?: ScriptKind;
138
}
139
```
140

141
**Usage Examples:**
142

143
```typescript
144
import { Project } from "ts-morph";
145

146
// Create project with tsconfig.json
147
const project = new Project({
148
  tsConfigFilePath: "tsconfig.json",
149
});
150

151
// Create project with custom compiler options
152
const project = new Project({
153
  compilerOptions: {
154
    target: ScriptTarget.ES2020,
155
    module: ModuleKind.ESNext,
156
    strict: true,
157
  },
158
});
159

160
// Add existing files
161
const sourceFile = project.addSourceFileAtPath("src/example.ts");
162

163
// Create new files
164
const newFile = project.createSourceFile("generated.ts", `
165
export class Generated {
166
  constructor(public name: string) {}
167
}
168
`);
169

170
// Work with the project
171
const files = project.getSourceFiles();
172
console.log(\`Project has \${files.length} files\`);
173

174
// Save changes
175
await project.save();
176
```
177

178
### Emit Result
179

180
Result of TypeScript compilation with diagnostic information.
181

182
```typescript { .api }
183
interface EmitResult {
184
  /** Whether the emit was successful */
185
  getEmitSkipped(): boolean;
186
  
187
  /** Get compilation diagnostics */
188
  getDiagnostics(): Diagnostic[];
189
}
190

191
interface Diagnostic {
192
  /** Get diagnostic message text */
193
  getMessageText(): string;
194
  
195
  /** Get source file where diagnostic occurred */
196
  getSourceFile(): SourceFile | undefined;
197
  
198
  /** Get diagnostic category */
199
  getCategory(): DiagnosticCategory;
200
  
201
  /** Get diagnostic code */
202
  getCode(): number;
203
  
204
  /** Get start position */
205
  getStart(): number | undefined;
206
  
207
  /** Get length */
208
  getLength(): number | undefined;
209
}
210

211
enum DiagnosticCategory {
212
  Warning = 0,
213
  Error = 1,
214
  Suggestion = 2,
215
  Message = 3,
216
}
217
```
218

219
### Manipulation Settings
220

221
Settings that control how code manipulation operations behave.
222

223
```typescript { .api }
224
interface ManipulationSettings {
225
  /** Indentation text to use */
226
  indentationText: string;
227
  
228
  /** New line kind */
229
  newLineKind: NewLineKind;
230
  
231
  /** Quote kind for strings */
232
  quoteKind: QuoteKind;
233
  
234
  /** Whether to use trailing commas */
235
  useTrailingCommas: boolean;
236
  
237
  /** Insert space after opening brace */
238
  insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces: boolean;
239
  
240
  /** Insert space after semicolon */
241
  insertSpaceAfterSemicolonInForStatements: boolean;
242
  
243
  /** Insert space before and after binary operators */
244
  insertSpaceBeforeAndAfterBinaryOperators: boolean;
245
}
246

247
enum QuoteKind {
248
  Single = "'",
249
  Double = "\"",
250
}
251

252
enum NewLineKind {
253
  /** \r\n */
254
  CarriageReturnLineFeed = "\r\n",
255
  /** \n */
256
  LineFeed = "\n",
257
}
258
```
259

260
### TypeScript Configuration Utilities
261

262
Utilities for working with TypeScript configuration files.
263

264
```typescript { .api }
265
/**
266
 * Get compiler options from a tsconfig.json file
267
 */
268
function getCompilerOptionsFromTsConfig(
269
  filePath: string,
270
  options?: CompilerOptionsFromTsConfigOptions
271
): CompilerOptionsFromTsConfigResult;
272

273
interface CompilerOptionsFromTsConfigOptions {
274
  /** Encoding for reading the file */
275
  encoding?: string;
276
  
277
  /** File system host to use */
278
  fileSystem?: FileSystemHost;
279
}
280

281
interface CompilerOptionsFromTsConfigResult {
282
  /** The resolved compiler options */
283
  options: CompilerOptions;
284
  
285
  /** Errors encountered while parsing */
286
  errors: Diagnostic[];
287
}
288
```
289

290
**Usage Examples:**
291

292
```typescript
293
import { getCompilerOptionsFromTsConfig } from "ts-morph";
294

295
// Parse tsconfig.json
296
const result = getCompilerOptionsFromTsConfig("./tsconfig.json");
297

298
if (result.errors.length > 0) {
299
  console.error("Errors in tsconfig.json:");
300
  result.errors.forEach(error => console.error(error.getMessageText()));
301
} else {
302
  console.log("Compiler options:", result.options);
303
}
304
```