Incremental migration
A JavaScript application is being converted file by file and must keep old and new modules working together.
TypeScript · Const
allowJs
allowJs lets a TypeScript project include and import JavaScript files, enabling mixed JS/TS codebases. It is useful for incremental migration and can support generating declaration files from JavaScript.
How it works
Set allowJs to true to include JavaScript files as project inputs, so .js and .jsx modules can coexist with TypeScript files and be imported by them. It is also useful when gradually converting a JavaScript project or when producing declaration files from JavaScript with declaration and emitDeclarationOnly.
Syntax
{"compilerOptions":{"allowJs":true}}Parameters
| Name | Type | Description |
|---|---|---|
allowJs | boolean | Boolean compiler option. Set to true to allow JavaScript files as project inputs. |
Key points
- The option expands importable project source beyond TypeScript files to include JavaScript files.
- It supports gradual migration by allowing TypeScript and pre-existing JavaScript to remain together during conversion.
- A mixed codebase can contain TypeScript files alongside its existing JavaScript files.
- Combining the option with declaration and emitDeclarationOnly enables declaration generation from JavaScript sources.
Common mistakes
- allowJs includes JavaScript files, but type-checking those files requires the separate checkJs option or an equivalent file-level directive.
Example: Import a JavaScript module from TypeScript
// card.js
export const defaultCardDeck = "Heart";
// index.ts
import { defaultCardDeck } from "./card";
console.log(defaultCardDeck);With allowJs enabled, the TypeScript file can import the JavaScript module.
When to use it
Mixed JavaScript and TypeScript
TypeScript modules need to import existing .js or .jsx modules in the same project.
Declaration generation
A library wants to publish .d.ts files derived from JSDoc-annotated JavaScript.
Interview questions
QWhat does allowJs do?
allowJs is a compiler option that permits JavaScript files to be part of a TypeScript program. Without it, imports are limited to TypeScript source extensions such as .ts and .tsx.
Follow-up: How would you migrate a JavaScript codebase incrementally? Enable allowJs so existing JavaScript and new TypeScript files can live together, then convert files over time.
QHow do you enable allowJs in a project?
Set allowJs to true in compilerOptions. This lets TypeScript accept JavaScript modules as inputs and allows TypeScript files to import them.
Follow-up: How can JavaScript receive diagnostics too? Enable checkJs, which asks TypeScript to report errors in the included JavaScript files.
QWhat is a practical use of allowJs beyond mixed-source imports?
allowJs can be combined with declaration and emitDeclarationOnly to generate declaration files for JavaScript sources. This supports publishing type information while retaining JavaScript implementation files.
Follow-up: What does emitDeclarationOnly change? It makes the declaration-generation run emit only .d.ts output instead of JavaScript output.
Related
checkJsdeclarationemitDeclarationOnly