0
# TypeScript Projects
1

2
Complete TypeScript project setup with compilation, testing, linting, and documentation generation. Provides a fully configured TypeScript development environment with modern tooling.
3

4
## Capabilities
5

6
### TypeScriptProject Class
7

8
Main TypeScript project class that extends NodeProject with TypeScript-specific features and tooling.
9

10
```typescript { .api }
11
/**
12
 * TypeScript project with build toolchain, testing, and development tools
13
 * Extends NodeProject with TypeScript compilation and type checking
14
 */
15
class TypeScriptProject extends NodeProject {
16
  constructor(options: TypeScriptProjectOptions);
17
  
18
  /** Source directory for TypeScript files (default: "src") */
19
  readonly srcdir: string;
20
  /** Compiled output directory (default: "lib") */
21
  readonly libdir: string;
22
  /** Test directory (default: "test") */
23
  readonly testdir: string;
24
  /** Main TypeScript configuration file */
25
  readonly tsconfig?: TypescriptConfig;
26
  /** Development TypeScript configuration */
27
  readonly tsconfigDev: TypescriptConfig;
28
  /** ESLint TypeScript configuration file */
29
  readonly tsconfigEslint?: TypescriptConfig;
30
  /** ESLint configuration for TypeScript */
31
  readonly eslint?: Eslint;
32
  /** Watch task for development */
33
  readonly watchTask: Task;
34
  /** Documentation generation enabled */
35
  readonly docgen?: boolean;
36
  /** Documentation output directory */
37
  readonly docsDirectory: string;
38
}
39

40
interface TypeScriptProjectOptions extends NodeProjectOptions {
41
  /** Source directory (default: "src") */
42
  srcdir?: string;
43
  /** Compiled output directory (default: "lib") */
44
  libdir?: string;
45
  /** Test directory (default: "test") */
46
  testdir?: string;
47
  /** TypeScript compiler options */
48
  tsconfig?: TypescriptConfigOptions;
49
  /** Development TypeScript compiler options */
50
  tsconfigDev?: TypescriptConfigOptions;
51
  /** The name of the development tsconfig.json file (default: "tsconfig.dev.json") */
52
  tsconfigDevFile?: string;
53
  /** Disable TypeScript compilation */
54
  disableTsconfig?: boolean;
55
  /** Do not generate a tsconfig.dev.json file */
56
  disableTsconfigDev?: boolean;
57
  /** TypeScript version to use (default: "latest") */
58
  typescriptVersion?: string;
59
  /** Enable TypeScript ESLint (default: true) */
60
  eslint?: boolean;
61
  /** ESLint configuration options */
62
  eslintOptions?: EslintOptions;
63
  /** Enable documentation generation with typedoc */
64
  docgen?: boolean;
65
  /** Documentation output directory (default: "docs") */
66
  docsDirectory?: string;
67
  /** Sample code generation (default: true) */
68
  sampleCode?: boolean;
69
  /** The .d.ts file that includes the type declarations for this module */
70
  entrypointTypes?: string;
71
  /** Use TypeScript for your projenrc file (.projenrc.ts) */
72
  projenrcTs?: boolean;
73
  /** Options for .projenrc.ts */
74
  projenrcTsOptions?: ProjenrcTsOptions;
75
  /** Options for ts-jest */
76
  tsJestOptions?: TsJestOptions;
77
}
78
```
79

80
**Basic Usage Example:**
81

82
```typescript
83
import { TypeScriptProject } from "projen";
84

85
const project = new TypeScriptProject({
86
  name: "my-typescript-lib",
87
  defaultReleaseBranch: "main",
88
  
89
  // Author information
90
  author: "Jane Developer",
91
  authorEmail: "jane@example.com",
92
  repository: "https://github.com/user/my-typescript-lib.git",
93
  
94
  // TypeScript configuration
95
  srcdir: "src",
96
  testdir: "test",
97
  libdir: "lib",
98
  
99
  // Dependencies
100
  deps: ["axios", "lodash"],
101
  devDeps: ["@types/node", "@types/lodash"],
102
  peerDeps: ["react"],
103
  
104
  // Tooling
105
  eslint: true,
106
  prettier: true,
107
  jest: true,
108
  
109
  // Documentation
110
  docgen: true,
111
  
112
  // Sample files
113
  sampleCode: true,
114
});
115

116
project.synth();
117
```
118

119
### TypeScript Configuration
120

121
TypeScript configuration file management with flexible compiler options.
122

123
```typescript { .api }
124
/**
125
 * Manages TypeScript configuration files (tsconfig.json)
126
 */
127
class TypescriptConfig extends Component {
128
  constructor(project: Project, options?: TypescriptConfigOptions);
129
  
130
  /** TypeScript compiler options */
131
  readonly compilerOptions: any;
132
  /** Files to include in compilation */
133
  readonly include?: string[];
134
  /** Files to exclude from compilation */
135
  readonly exclude?: string[];
136
  
137
  /** Add include pattern */
138
  addInclude(pattern: string): void;
139
  /** Add exclude pattern */
140
  addExclude(pattern: string): void;
141
}
142

143
interface TypescriptConfigOptions {
144
  /** TypeScript compiler options */
145
  compilerOptions?: any;
146
  /** Files to include */
147
  include?: string[];
148
  /** Files to exclude */
149
  exclude?: string[];
150
  /** Extend from another tsconfig */
151
  extends?: string;
152
}
153
```
154

155
**TypeScript Configuration Example:**
156

157
```typescript
158
import { TypeScriptProject } from "projen";
159

160
const project = new TypeScriptProject({
161
  name: "advanced-ts-project",
162
  tsconfig: {
163
    compilerOptions: {
164
      target: "ES2020",
165
      module: "commonjs",
166
      lib: ["ES2020", "DOM"],
167
      strict: true,
168
      esModuleInterop: true,
169
      skipLibCheck: true,
170
      forceConsistentCasingInFileNames: true,
171
    },
172
    include: ["src/**/*"],
173
    exclude: ["node_modules", "lib"],
174
  },
175
  tsconfigDev: {
176
    compilerOptions: {
177
      noEmit: true,
178
    },
179
    include: ["src/**/*", "test/**/*"],
180
  },
181
});
182
```
183

184
### Projenrc TypeScript
185

186
TypeScript-based projen configuration with full type safety.
187

188
```typescript { .api }
189
/**
190
 * TypeScript projenrc configuration file
191
 * Provides type-safe project configuration
192
 */
193
class ProjenrcTs extends Component {
194
  constructor(project: TypeScriptProject, options?: ProjenrcOptions);
195
}
196

197
interface ProjenrcOptions {
198
  /** Filename for the projenrc file (default: ".projenrc.ts") */
199
  filename?: string;
200
  /** Use ts-node for execution (default: true) */
201
  tsNode?: boolean;
202
}
203
```
204

205
**Projenrc TypeScript Example:**
206

207
```typescript
208
// .projenrc.ts
209
import { TypeScriptProject } from "projen";
210

211
const project = new TypeScriptProject({
212
  name: "my-project",
213
  defaultReleaseBranch: "main",
214
  
215
  // Full TypeScript IntelliSense support
216
  deps: ["axios"],
217
  devDeps: ["@types/node"],
218
  
219
  // Type-safe configuration
220
  tsconfig: {
221
    compilerOptions: {
222
      target: "ES2020",
223
      strict: true,
224
    },
225
  },
226
});
227

228
// Custom configuration with full type checking
229
project.addTask("custom-task", {
230
  description: "Custom build step",
231
  exec: "echo 'Custom task executed'",
232
});
233

234
project.synth();
235
```
236

237
### Documentation Generation
238

239
Automatic API documentation generation using TypeDoc.
240

241
```typescript { .api }
242
/**
243
 * TypeDoc documentation generation for TypeScript projects
244
 */
245
class TypedocDocgen extends Component {
246
  constructor(project: TypeScriptProject, options?: TypedocOptions);
247
}
248

249
interface TypedocOptions {
250
  /** Entry point for documentation */
251
  entryPoint?: string;
252
  /** Output directory (default: "docs") */
253
  out?: string;
254
  /** Include private members */
255
  includePrivate?: boolean;
256
  /** TypeDoc theme */
257
  theme?: string;
258
  /** Additional TypeDoc options */
259
  options?: any;
260
}
261
```
262

263
**Documentation Example:**
264

265
```typescript
266
import { TypeScriptProject } from "projen";
267

268
const project = new TypeScriptProject({
269
  name: "documented-project",
270
  
271
  // Enable documentation generation
272
  docgen: true,
273
  typedocOptions: {
274
    entryPoint: "src/index.ts",
275
    out: "api-docs",
276
    theme: "default",
277
    includePrivate: false,
278
  },
279
});
280

281
// Documentation will be generated in the "api-docs" directory
282
// Available via npm run docgen
283
```
284

285
### Advanced TypeScript Features
286

287
Additional TypeScript-specific features and configurations.
288

289
```typescript { .api }
290
/**
291
 * TypeScript application project (for applications vs libraries)
292
 */
293
class TypeScriptAppProject extends TypeScriptProject {
294
  constructor(options: TypeScriptAppProjectOptions);
295
}
296

297
interface TypeScriptAppProjectOptions extends TypeScriptProjectOptions {
298
  /** Application entry point */
299
  entrypoint?: string;
300
  /** Enable bundling with esbuild */
301
  bundle?: boolean;
302
  /** Bundling options */
303
  bundlerOptions?: BundlerOptions;
304
}
305
```
306

307
**TypeScript Application Example:**
308

309
```typescript
310
import { TypeScriptAppProject } from "projen";
311

312
const app = new TypeScriptAppProject({
313
  name: "my-typescript-app",
314
  defaultReleaseBranch: "main",
315
  
316
  // Application-specific settings
317
  entrypoint: "src/main.ts",
318
  bundle: true,
319
  
320
  // Runtime dependencies
321
  deps: [
322
    "express",
323
    "cors",
324
  ],
325
  
326
  // Development dependencies
327
  devDeps: [
328
    "@types/express",
329
    "@types/cors",
330
    "@types/node",
331
  ],
332
});
333

334
// Add application-specific tasks
335
app.addTask("start", {
336
  description: "Start the application",
337
  exec: "node lib/main.js",
338
});
339

340
app.addTask("dev", {
341
  description: "Start in development mode",
342
  exec: "ts-node src/main.ts",
343
});
344
```
345

346
## Types
347

348
### TypeScript-Specific Types
349

350
```typescript { .api }
351
interface BundlerOptions {
352
  /** Bundler to use (esbuild, webpack) */
353
  bundler?: "esbuild" | "webpack";
354
  /** Bundle format */
355
  format?: "cjs" | "esm";
356
  /** External dependencies */
357
  externals?: string[];
358
  /** Target environment */
359
  target?: string;
360
}
361

362
interface EslintOptions {
363
  /** ESLint configuration directories */
364
  dirs?: string[];
365
  /** File extensions to lint */
366
  fileExtensions?: string[];
367
  /** Ignore patterns */
368
  ignorePatterns?: string[];
369
  /** Additional ESLint rules */
370
  rules?: Record<string, any>;
371
}
372
```