0
# Configuration
1

2
Comprehensive configuration options for tsify, including TypeScript compiler options and tsify-specific settings.
3

4
## Capabilities
5

6
### TsifyOptions Interface
7

8
Complete configuration interface supporting all TypeScript compiler options and tsify-specific settings.
9

10
```typescript { .api }
11
interface TsifyOptions {
12
  // tsify-specific options
13
  /** Files/patterns to exclude from compilation */
14
  exclude?: string[];
15
  /** Explicit list of files to compile */
16
  files?: string[];
17
  /** Whether to set up as global transform */
18
  global?: boolean;
19
  /** Files/patterns to include in compilation */
20
  include?: string[];
21
  /** Short form for module option */
22
  m?: string;
23
  /** Short form for project option */
24
  p?: string | Record<string, any>;
25
  /** Path to tsconfig.json file or directory, or inline tsconfig object */
26
  project?: string | Record<string, any>;
27
  /** Short form for target option */
28
  t?: string;
29
  /** Custom TypeScript compiler reference */
30
  typescript?: string | typeof import('typescript');
31
  
32
  // TypeScript Compiler Options (commonly used)
33
  /** Allow JavaScript files to be compiled */
34
  allowJs?: boolean;
35
  /** Allow importing modules with .json extension */
36
  allowSyntheticDefaultImports?: boolean;
37
  /** Allow default imports from modules without default export */
38
  esModuleInterop?: boolean;
39
  /** Ensure consistent casing in file names */
40
  forceConsistentCasingInFileNames?: boolean;
41
  /** Enable all strict type checking options */
42
  strict?: boolean;
43
  /** Raise error on expressions and declarations with implied any type */
44
  noImplicitAny?: boolean;
45
  /** Raise error on this expressions with implied any type */
46
  noImplicitThis?: boolean;
47
  /** Report errors for fallthrough cases in switch statements */
48
  noFallthroughCasesInSwitch?: boolean;
49
  /** Report errors on unused locals */
50
  noUnusedLocals?: boolean;
51
  /** Report errors on unused parameters */
52
  noUnusedParameters?: boolean;
53
  /** Enable strict null checks */
54
  strictNullChecks?: boolean;
55
  /** Enable strict function types */
56
  strictFunctionTypes?: boolean;
57
  /** Enable strict bind/call/apply methods */
58
  strictBindCallApply?: boolean;
59
  /** Enable strict property initialization checks */
60
  strictPropertyInitialization?: boolean;
61
  /** JSX code generation */
62
  jsx?: 'preserve' | 'react' | 'react-jsx' | 'react-jsxdev' | 'react-native';
63
  /** Specify JSX factory function */
64
  jsxFactory?: string;
65
  /** Specify JSX fragment factory function */
66
  jsxFragmentFactory?: string;
67
  /** Module system */
68
  module?: 'commonjs' | 'amd' | 'system' | 'umd' | 'es6' | 'es2015' | 'es2020' | 'esnext' | 'none';
69
  /** Module resolution strategy */
70
  moduleResolution?: 'node' | 'classic';
71
  /** ECMAScript target version */
72
  target?: 'es3' | 'es5' | 'es6' | 'es2015' | 'es2016' | 'es2017' | 'es2018' | 'es2019' | 'es2020' | 'es2021' | 'esnext';
73
  /** List of library files to include in compilation */
74
  lib?: string[];
75
  /** Base directory for resolving non-relative module names */
76
  baseUrl?: string;
77
  /** Path mapping entries for module resolution */
78
  paths?: Record<string, string[]>;
79
  /** Allow accessing UMD globals from modules */
80
  allowUmdGlobalAccess?: boolean;
81
  /** Remove comments from output */
82
  removeComments?: boolean;
83
  /** Emit design-type metadata for decorated declarations */
84
  emitDecoratorMetadata?: boolean;
85
  /** Enable experimental decorators */
86
  experimentalDecorators?: boolean;
87
  /** Skip type checking of declaration files */
88
  skipLibCheck?: boolean;
89
  /** Do not emit outputs if any errors were reported */
90
  noEmitOnError?: boolean;
91
  /** Preserve const enums in generated code */
92
  preserveConstEnums?: boolean;
93
  /** Do not erase const enum declarations */
94
  isolatedModules?: boolean;
95
  /** Import emit helpers from 'tslib' */
96
  importHelpers?: boolean;
97
  /** Downlevel iteration for ES5/ES3 */
98
  downlevelIteration?: boolean;
99
  /** Enable incremental compilation */
100
  incremental?: boolean;
101
  /** Specify file to store incremental compilation information */
102
  tsBuildInfoFile?: string;
103
}
104
```
105

106
### Configuration Sources
107

108
tsify reads configuration from multiple sources in order of precedence:
109

110
1. **Inline options** passed to the plugin
111
2. **tsconfig.json** file (automatic detection or specified path)
112
3. **Default values**
113

114
**Automatic tsconfig.json Detection:**
115
```javascript
116
// tsify automatically finds tsconfig.json in current directory or parent directories
117
browserify()
118
  .add('src/main.ts')
119
  .plugin(tsify)  // Uses tsconfig.json automatically
120
  .bundle();
121
```
122

123
**Custom tsconfig.json Path:**
124
```javascript
125
browserify()
126
  .add('src/main.ts')
127
  .plugin(tsify, {
128
    project: './config/custom-tsconfig.json'
129
  })
130
  .bundle();
131
```
132

133
**Inline Configuration:**
134
```javascript
135
browserify()
136
  .add('src/main.ts')
137
  .plugin(tsify, {
138
    project: {
139
      compilerOptions: {
140
        target: 'es2017',
141
        strict: true,
142
        esModuleInterop: true,
143
        allowJs: true
144
      },
145
      include: ['src/**/*']
146
    }
147
  })
148
  .bundle();
149
```
150

151
### Option Overrides
152

153
tsify overrides certain TypeScript compiler options for Browserify compatibility:
154

155
**Always Overridden:**
156
- `sourceMap` → `false` (uses inline source maps when `--debug` is set)
157
- `inlineSourceMap` → Set based on Browserify's `--debug` option
158
- `inlineSources` → Set based on Browserify's `--debug` option
159
- `module` → Defaults to `commonjs` for Browserify compatibility
160
- `rootDir` → Set internally for proper file resolution
161
- `outDir` → Set internally to virtual output directory
162

163
**Blacklisted Options (ignored):**
164
- `out` - Use Browserify's output options instead
165
- `outFile` - Use Browserify's output options instead
166
- `noEmit` - Must emit for bundling to work
167

168
### File Inclusion Options
169

170
Control which files are included in TypeScript compilation:
171

172
```javascript { .api }
173
interface FileInclusionOptions {
174
  /** Explicit list of files to compile (overrides tsconfig files) */
175
  files?: string[];
176
  /** Glob patterns to include */
177
  include?: string[];
178
  /** Glob patterns to exclude */
179
  exclude?: string[];
180
}
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Only compile entry points and their dependencies
187
browserify()
188
  .add('src/main.ts')
189
  .plugin(tsify, {
190
    files: []  // Empty array means only entry points
191
  })
192
  .bundle();
193

194
// Include/exclude patterns
195
browserify()
196
  .add('src/main.ts')
197
  .plugin(tsify, {
198
    include: ['src/**/*'],
199
    exclude: ['**/*.test.ts', 'node_modules/**']
200
  })
201
  .bundle();
202
```
203

204
### Advanced Configuration
205

206
**Custom TypeScript Compiler:**
207
```javascript
208
const ntypescript = require('ntypescript');
209

210
browserify()
211
  .add('main.ts')
212
  .plugin(tsify, {
213
    typescript: ntypescript  // Use alternative compiler
214
  })
215
  .bundle();
216

217
// Or by name
218
browserify()
219
  .add('main.ts')
220
  .plugin(tsify, {
221
    typescript: 'ntypescript'
222
  })
223
  .bundle();
224
```
225

226
**Global Transform Mode:**
227
```javascript
228
browserify()
229
  .add('src/app.ts')
230
  .plugin(tsify, {
231
    global: true,      // Process all files, not just dependencies
232
    allowJs: true      // Include JavaScript files
233
  })
234
  .bundle();
235
```
236

237
### Configuration Examples
238

239
**React/JSX Setup:**
240
```javascript
241
browserify()
242
  .add('src/App.tsx')
243
  .plugin(tsify, {
244
    jsx: 'react-jsx',
245
    esModuleInterop: true,
246
    allowSyntheticDefaultImports: true,
247
    strict: true
248
  })
249
  .bundle();
250
```
251

252
**ES2020 with Decorators:**
253
```javascript
254
browserify()
255
  .add('src/main.ts')
256
  .plugin(tsify, {
257
    target: 'es2020',
258
    experimentalDecorators: true,
259
    emitDecoratorMetadata: true,
260
    strictPropertyInitialization: false
261
  })
262
  .bundle();
263
```
264

265
**Strict Mode with Path Mapping:**
266
```javascript
267
browserify()
268
  .add('src/main.ts')
269
  .plugin(tsify, {
270
    strict: true,
271
    baseUrl: './src',
272
    paths: {
273
      '@components/*': ['components/*'],
274
      '@utils/*': ['utils/*']
275
    }
276
  })
277
  .bundle();
278
```
279

280
## Types
281

282
```typescript { .api }
283
interface ConfigurationContext {
284
  /** Current working directory */
285
  currentDirectory: string;
286
  /** Browserify options */
287
  browserifyOptions: any;
288
  /** Resolved tsconfig.json path */
289
  configFile?: string;
290
  /** Parsed TypeScript configuration */
291
  parsedConfig: {
292
    options: any;
293
    fileNames: string[];
294
  };
295
}
296
```