0
# Project Configuration
1

2
jsii-config provides an interactive CLI tool for configuring jsii module settings in package.json. It guides developers through setting up target language configurations, metadata, and build settings for multi-language library projects.
3

4
## Capabilities
5

6
### Main Configuration Function
7

8
The primary entry point for interactive jsii project configuration.
9

10
```typescript { .api }
11
/**
12
 * Main function for interactive jsii configuration
13
 * Prompts user for project settings and updates package.json
14
 * @returns Promise that resolves when configuration is complete
15
 */
16
function jsiiConfig(): Promise<void>;
17
```
18

19
**Usage Example:**
20

21
```bash
22
# Run interactive configuration
23
npx jsii-config
24

25
# The tool will prompt for various settings:
26
# - Project information (name, description, author)
27
# - Target language configurations
28
# - Metadata and build settings
29
```
30

31
### Configuration Interfaces
32

33
Type definitions for jsii configuration structure in package.json.
34

35
```typescript { .api }
36
/**
37
 * Structure of jsii configuration in package.json
38
 */
39
interface Config {
40
  /** Project metadata */
41
  projectInfo?: ProjectInfo;
42
  /** Target language configurations */
43
  targets?: Targets;
44
  /** Additional metadata */
45
  metadata?: ConfigMetadata;
46
  /** Excluded TypeScript files */
47
  excludeTypescript?: string[];
48
  /** Compression settings */
49
  compress?: boolean;
50
  /** Experimental features */
51
  experimentalFeatures?: {
52
    [feature: string]: boolean;
53
  };
54
  /** Assembly validation */
55
  validate?: {
56
    /** Whether to validate assembly */
57
    assembly?: boolean;
58
    /** Custom validation options */
59
    [option: string]: any;
60
  };
61
}
62

63
/**
64
 * Project information configuration
65
 */
66
interface ProjectInfo {
67
  /** Project name */
68
  name?: string;
69
  /** Project version */
70
  version?: string;
71
  /** Project description */
72
  description?: string;
73
  /** Project author */
74
  author?: PersonConfig;
75
  /** Project license */
76
  license?: string;
77
  /** Project homepage */
78
  homepage?: string;
79
  /** Project repository */
80
  repository?: RepositoryConfig;
81
  /** Project keywords */
82
  keywords?: string[];
83
  /** Project stability level */
84
  stability?: 'experimental' | 'stable' | 'deprecated';
85
}
86

87
/**
88
 * Person configuration (author, maintainer)
89
 */
90
interface PersonConfig {
91
  /** Person name */
92
  name?: string;
93
  /** Contact email */
94
  email?: string;
95
  /** Website URL */
96
  url?: string;
97
  /** Organization */
98
  organization?: string;
99
}
100

101
/**
102
 * Repository configuration
103
 */
104
interface RepositoryConfig {
105
  /** Repository type (git, svn, etc.) */
106
  type?: string;
107
  /** Repository URL */
108
  url?: string;
109
  /** Directory within repository */
110
  directory?: string;
111
}
112
```
113

114
### Target Language Configurations
115

116
Configuration interfaces for each supported target language.
117

118
```typescript { .api }
119
/**
120
 * Target language configurations
121
 */
122
interface Targets {
123
  /** JavaScript/TypeScript configuration */
124
  js?: JavaScriptConfig;
125
  /** Python configuration */
126
  python?: PythonConfig;
127
  /** Java configuration */
128
  java?: JavaConfig;
129
  /** .NET configuration */
130
  dotnet?: DotNetConfig;
131
  /** Go configuration */
132
  go?: GoConfig;
133
}
134

135
/**
136
 * JavaScript/npm target configuration
137
 */
138
interface JavaScriptConfig {
139
  /** npm package name */
140
  npm?: string;
141
  /** Package description override */
142
  description?: string;
143
  /** Package keywords */
144
  keywords?: string[];
145
  /** Package author override */
146
  author?: PersonConfig;
147
  /** Package homepage override */
148
  homepage?: string;
149
  /** Package repository override */
150
  repository?: RepositoryConfig;
151
}
152

153
/**
154
 * Python target configuration
155
 */
156
interface PythonConfig {
157
  /** PyPI distribution name */
158
  distName?: string;
159
  /** Python module name */
160
  module?: string;
161
  /** Package classifiers for PyPI */
162
  classifiers?: string[];
163
  /** Package description override */
164
  description?: string;
165
  /** Package homepage override */
166
  homepage?: string;
167
  /** Package author override */
168
  author?: PersonConfig;
169
  /** Package license override */
170
  license?: string;
171
  /** Package keywords */
172
  keywords?: string[];
173
  /** Poetry configuration */
174
  poetry?: {
175
    /** Poetry package name */
176
    name?: string;
177
    /** Include/exclude patterns */
178
    include?: string[];
179
    exclude?: string[];
180
  };
181
}
182

183
/**
184
 * Java target configuration
185
 */
186
interface JavaConfig {
187
  /** Java package name */
188
  package?: string;
189
  /** Maven configuration */
190
  maven?: {
191
    /** Maven group ID */
192
    groupId?: string;
193
    /** Maven artifact ID */
194
    artifactId?: string;
195
    /** Maven version override */
196
    version?: string;
197
    /** Package description override */
198
    description?: string;
199
    /** Package URL */
200
    url?: string;
201
    /** Developer information */
202
    developers?: Array<{
203
      name?: string;
204
      email?: string;
205
      organization?: string;
206
      url?: string;
207
    }>;
208
    /** SCM information */
209
    scm?: {
210
      connection?: string;
211
      developerConnection?: string;
212
      url?: string;
213
    };
214
    /** License information */
215
    licenses?: Array<{
216
      name?: string;
217
      url?: string;
218
      distribution?: string;
219
    }>;
220
  };
221
}
222

223
/**
224
 * .NET target configuration
225
 */
226
interface DotNetConfig {
227
  /** .NET namespace */
228
  namespace?: string;
229
  /** NuGet package ID */
230
  packageId?: string;
231
  /** Package title */
232
  title?: string;
233
  /** Package description override */
234
  description?: string;
235
  /** Package version override */
236
  version?: string;
237
  /** Package authors */
238
  authors?: string[];
239
  /** Company name */
240
  company?: string;
241
  /** Product name */
242
  product?: string;
243
  /** Copyright notice */
244
  copyright?: string;
245
  /** Package icon URL */
246
  iconUrl?: string;
247
  /** Package project URL */
248
  projectUrl?: string;
249
  /** Package license URL */
250
  licenseUrl?: string;
251
  /** Package tags */
252
  tags?: string[];
253
  /** Strong naming configuration */
254
  strongNaming?: {
255
    /** Whether to sign assembly */
256
    enabled?: boolean;
257
    /** Key file path */
258
    keyFile?: string;
259
  };
260
  /** XML documentation */
261
  xmlDoc?: boolean;
262
  /** Version suffix */
263
  versionSuffix?: string;
264
}
265

266
/**
267
 * Go target configuration
268
 */
269
interface GoConfig {
270
  /** Go module name */
271
  moduleName?: string;
272
  /** Go package name */
273
  packageName?: string;
274
  /** Package description override */
275
  description?: string;
276
  /** Package version override */
277
  version?: string;
278
  /** Git tag prefix */
279
  gitTagPrefix?: string;
280
  /** Go version constraint */
281
  goVersion?: string;
282
  /** Package import path */
283
  importPath?: string;
284
}
285
```
286

287
### Package.json Integration
288

289
Interface for the complete package.json structure with jsii configuration.
290

291
```typescript { .api }
292
/**
293
 * Structure of jsii module package.json
294
 */
295
interface PackageJson {
296
  /** Package name */
297
  name: string;
298
  /** Package version */
299
  version: string;
300
  /** Package description */
301
  description?: string;
302
  /** Main entry point */
303
  main?: string;
304
  /** TypeScript definitions */
305
  types?: string;
306
  /** Package author */
307
  author?: string | PersonConfig;
308
  /** Package license */
309
  license?: string;
310
  /** Package homepage */
311
  homepage?: string;
312
  /** Package repository */
313
  repository?: string | RepositoryConfig;
314
  /** Package keywords */
315
  keywords?: string[];
316
  /** Runtime dependencies */
317
  dependencies?: { [name: string]: string };
318
  /** Development dependencies */
319
  devDependencies?: { [name: string]: string };
320
  /** Peer dependencies */
321
  peerDependencies?: { [name: string]: string };
322
  /** Bundle dependencies */
323
  bundledDependencies?: string[];
324
  /** NPM scripts */
325
  scripts?: { [name: string]: string };
326
  /** Package bin commands */
327
  bin?: string | { [name: string]: string };
328
  /** Files to include in package */
329
  files?: string[];
330
  /** Node.js engine requirements */
331
  engines?: { [engine: string]: string };
332
  /** Package exports */
333
  exports?: any;
334
  /** ESM type */
335
  type?: 'module' | 'commonjs';
336
  /** jsii configuration */
337
  jsii?: Config;
338
  /** Additional package.json fields */
339
  [key: string]: any;
340
}
341
```
342

343
### Configuration Metadata
344

345
Additional metadata and build configuration options.
346

347
```typescript { .api }
348
/**
349
 * Additional configuration metadata
350
 */
351
interface ConfigMetadata {
352
  /** jsii compiler version */
353
  jsiiVersion?: string;
354
  /** Assembly fingerprint */
355
  fingerprint?: string;
356
  /** Assembly compression */
357
  compression?: {
358
    /** Enable compression */
359
    enabled?: boolean;
360
    /** Compression level */
361
    level?: number;
362
  };
363
  /** Documentation configuration */
364
  docs?: {
365
    /** Documentation format */
366
    format?: 'markdown' | 'restructured-text' | 'html';
367
    /** Custom documentation metadata */
368
    [key: string]: any;
369
  };
370
  /** Code examples configuration */
371
  examples?: {
372
    /** Example source directories */
373
    sourceDirs?: string[];
374
    /** Example cache directory */
375
    cacheDir?: string;
376
    /** Whether to validate examples */
377
    validate?: boolean;
378
  };
379
}
380

381
/**
382
 * Validation configuration options
383
 */
384
interface ValidationConfig {
385
  /** Whether to validate assembly schema */
386
  assembly?: boolean;
387
  /** Whether to validate TypeScript types */
388
  types?: boolean;
389
  /** Whether to validate documentation */
390
  docs?: boolean;
391
  /** Custom validation rules */
392
  rules?: {
393
    [ruleName: string]: boolean | any;
394
  };
395
}
396
```
397

398
### Interactive Prompting
399

400
Functions and utilities for interactive configuration prompting.
401

402
```typescript { .api }
403
/**
404
 * Interactive prompting for configuration values
405
 * @param questions Array of prompt questions
406
 * @returns Promise resolving to user answers
407
 */
408
function prompt(questions: PromptQuestion[]): Promise<{ [key: string]: any }>;
409

410
/**
411
 * Prompt question definition
412
 */
413
interface PromptQuestion {
414
  /** Question type */
415
  type: 'input' | 'confirm' | 'list' | 'checkbox' | 'password';
416
  /** Question name/key */
417
  name: string;
418
  /** Question message */
419
  message: string;
420
  /** Default value */
421
  default?: any;
422
  /** Available choices for list/checkbox */
423
  choices?: Array<string | { name: string; value: any }>;
424
  /** Validation function */
425
  validate?: (input: any) => boolean | string;
426
  /** When to show this question */
427
  when?: (answers: any) => boolean;
428
  /** Transform function for answer */
429
  filter?: (input: any) => any;
430
}
431

432
/**
433
 * Configuration wizard that walks through jsii setup
434
 * @param packageJsonPath Path to package.json file
435
 * @param options Wizard options
436
 */
437
function configurationWizard(
438
  packageJsonPath: string,
439
  options?: {
440
    /** Skip existing configuration */
441
    skipExisting?: boolean;
442
    /** Force overwrite existing settings */
443
    force?: boolean;
444
    /** Interactive mode */
445
    interactive?: boolean;
446
  }
447
): Promise<void>;
448

449
/**
450
 * Validate configuration values
451
 * @param config Configuration to validate
452
 * @returns Validation result
453
 */
454
function validateConfiguration(config: Config): {
455
  valid: boolean;
456
  errors?: Array<{
457
    path: string;
458
    message: string;
459
  }>;
460
  warnings?: Array<{
461
    path: string;
462
    message: string;
463
  }>;
464
};
465
```
466

467
### File System Utilities
468

469
Helper functions for reading, writing, and validating configuration files.
470

471
```typescript { .api }
472
/**
473
 * Promise-based file reading utility
474
 * @param filePath Path to file to read
475
 * @returns Promise resolving to file contents
476
 */
477
function readFilePromise(filePath: string): Promise<string>;
478

479
/**
480
 * Write package.json with jsii configuration
481
 * @param filePath Path to package.json
482
 * @param packageJson Package.json content with jsii config
483
 * @param options Write options
484
 */
485
function writePackageJson(
486
  filePath: string, 
487
  packageJson: PackageJson,
488
  options?: {
489
    /** Indentation spaces */
490
    indent?: number;
491
    /** Sort keys alphabetically */
492
    sortKeys?: boolean;
493
  }
494
): Promise<void>;
495

496
/**
497
 * Validate package.json structure
498
 * @param packageJson Package.json content
499
 * @returns Validation result
500
 */
501
function validatePackageJson(packageJson: any): {
502
  valid: boolean;
503
  errors?: string[];
504
  warnings?: string[];
505
};
506

507
/**
508
 * Merge jsii configuration into existing package.json
509
 * @param existingPackageJson Current package.json content
510
 * @param jsiiConfig New jsii configuration
511
 * @returns Merged package.json
512
 */
513
function mergeJsiiConfig(
514
  existingPackageJson: PackageJson,
515
  jsiiConfig: Config
516
): PackageJson;
517

518
/**
519
 * Load existing jsii configuration from package.json
520
 * @param packageJsonPath Path to package.json
521
 * @returns Existing jsii configuration or undefined
522
 */
523
function loadExistingConfig(packageJsonPath: string): Promise<Config | undefined>;
524

525
/**
526
 * Create default jsii configuration
527
 * @param packageJson Current package.json content
528
 * @returns Default jsii configuration
529
 */
530
function createDefaultConfig(packageJson: PackageJson): Config;
531
```
532

533
### Target Validation and Utilities
534

535
Helper functions for validating and working with target configurations.
536

537
```typescript { .api }
538
/**
539
 * Validate target configuration
540
 * @param target Target name
541
 * @param config Target configuration
542
 * @returns Validation result
543
 */
544
function validateTargetConfig(
545
  target: string, 
546
  config: any
547
): {
548
  valid: boolean;
549
  errors?: string[];
550
  warnings?: string[];
551
};
552

553
/**
554
 * Get available target languages
555
 * @returns Array of supported target language names
556
 */
557
function getAvailableTargets(): string[];
558

559
/**
560
 * Get default configuration for target language
561
 * @param target Target language name
562
 * @param packageJson Current package.json content
563
 * @returns Default target configuration
564
 */
565
function getDefaultTargetConfig(target: string, packageJson: PackageJson): any;
566

567
/**
568
 * Normalize target configuration
569
 * @param target Target name
570
 * @param config Raw target configuration
571
 * @returns Normalized configuration
572
 */
573
function normalizeTargetConfig(target: string, config: any): any;
574

575
/**
576
 * Check if target is supported
577
 * @param target Target name to check
578
 * @returns Whether target is supported
579
 */
580
function isTargetSupported(target: string): boolean;
581
```
582

583
## Types
584

585
```typescript { .api }
586
/**
587
 * Configuration wizard step
588
 */
589
interface WizardStep {
590
  /** Step identifier */
591
  id: string;
592
  /** Step title */
593
  title: string;
594
  /** Step description */
595
  description?: string;
596
  /** Step questions */
597
  questions: PromptQuestion[];
598
  /** Step completion check */
599
  isComplete?: (answers: any) => boolean;
600
}
601

602
/**
603
 * Configuration template
604
 */
605
interface ConfigTemplate {
606
  /** Template name */
607
  name: string;
608
  /** Template description */
609
  description: string;
610
  /** Template configuration */
611
  config: Partial<Config>;
612
  /** Template package.json changes */
613
  packageJson?: Partial<PackageJson>;
614
}
615

616
/**
617
 * Available configuration templates
618
 */
619
const CONFIG_TEMPLATES: readonly ConfigTemplate[];
620
```
621

622
**Usage Examples:**
623

624
```typescript
625
// Run interactive configuration
626
import jsiiConfig from 'jsii-config';
627

628
// Interactive setup
629
await jsiiConfig();
630

631
// Programmatic configuration
632
import { configurationWizard, validateConfiguration } from 'jsii-config';
633

634
const config: Config = {
635
  targets: {
636
    python: {
637
      distName: 'my-awesome-library',
638
      module: 'my_awesome_library',
639
      classifiers: [
640
        'Development Status :: 5 - Production/Stable',
641
        'Programming Language :: Python :: 3.8',
642
        'Programming Language :: Python :: 3.9'
643
      ]
644
    },
645
    java: {
646
      package: 'com.example.mylib',
647
      maven: {
648
        groupId: 'com.example',
649
        artifactId: 'my-library'
650
      }
651
    },
652
    dotnet: {
653
      namespace: 'MyCompany.MyLibrary',
654
      packageId: 'MyCompany.MyLibrary'
655
    }
656
  },
657
  metadata: {
658
    jsiiVersion: '^5.0.0',
659
    docs: {
660
      format: 'markdown'
661
    }
662
  }
663
};
664

665
const validation = validateConfiguration(config);
666
if (validation.valid) {
667
  console.log('Configuration is valid');
668
} else {
669
  console.error('Validation errors:', validation.errors);
670
}
671

672
// Load and modify existing configuration
673
import { loadExistingConfig, mergeJsiiConfig } from 'jsii-config';
674

675
const existing = await loadExistingConfig('./package.json');
676
const updated = mergeJsiiConfig(packageJson, {
677
  targets: {
678
    go: {
679
      moduleName: 'github.com/example/my-library-go'
680
    }
681
  }
682
});
683
```