TypeScript doesn’t exist in a vacuum.\nIt was built with the JavaScript ecosystem in mind, and a lot of JavaScript exists today.\nConverting a JavaScript codebase over to TypeScript is, while somewhat tedious, usually not challenging.\nIn this tutorial, we’re going to look at how you might start out.\nWe assume you’ve read enough of the handbook to write new TypeScript code.
\nIf you’re looking to convert a React project, we recommend looking at the React Conversion Guide first.
\nIf you’re writing in plain JavaScript, it’s likely that you’re running your JavaScript directly,\nwhere your .js files are in a src, lib, or dist directory, and then ran as desired.
If that’s the case, the files that you’ve written are going to be used as inputs to TypeScript, and you’ll run the outputs it produces.\nDuring our JS to TS migration, we’ll need to separate our input files to prevent TypeScript from overwriting them.\nIf your output files need to reside in a specific directory, then that will be your output directory.
\nYou might also be running some intermediate steps on your JavaScript, such as bundling or using another transpiler like Babel.\nIn this case, you might already have a folder structure like this set up.
\nFrom this point on, we’re going to assume that your directory is set up something like this:
\nprojectRoot\n├── src\n│ ├── file1.js\n│ └── file2.js\n├── built\n└── tsconfig.json\nIf you have a tests folder outside of your src directory, you might have one tsconfig.json in src, and one in tests as well.
TypeScript uses a file called tsconfig.json for managing your project’s options, such as which files you want to include, and what sorts of checking you want to perform.\nLet’s create a bare-bones one for our project:
\njson{\n \"compilerOptions\": {\n \"outDir\": \"./built\",\n \"allowJs\": true,\n \"target\": \"es5\"\n },\n \"include\": [\n \"./src/**/*\"\n ]\n}
Here we’re specifying a few things to TypeScript:
\nsrc directory (with include).allowJs).built (with outDir).target).At this point, if you try running tsc at the root of your project, you should see output files in the built directory.\nThe layout of files in built should look identical to the layout of src.\nYou should now have TypeScript working with your project.
Even at this point you can get some great benefits from TypeScript understanding your project.\nIf you open up an editor like VS Code or Visual Studio, you’ll see that you can often get some tooling support like completion.\nYou can also catch certain bugs with options like:
\nnoImplicitReturns which prevents you from forgetting to return at the end of a function.noFallthroughCasesInSwitch which is helpful if you never want to forget a break statement between cases in a switch block.TypeScript will also warn about unreachable code and labels, which you can disable with allowUnreachableCode and allowUnusedLabels respectively.
You might have some more build steps in your pipeline.\nPerhaps you concatenate something to each of your files.\nEach build tool is different, but we’ll do our best to cover the gist of things.
\nIf you’re using Gulp in some fashion, we have a tutorial on using Gulp with TypeScript, and integrating with common build tools like Browserify, Babelify, and Uglify.\nYou can read more there.
\nWebpack integration is pretty simple.\nYou can use awesome-typescript-loader, a TypeScript loader, combined with source-map-loader for easier debugging.\nSimply run
\nshellnpm install awesome-typescript-loader source-map-loader
and merge in options from the following into your webpack.config.js file:
\njsmodule.exports = {\n entry: \"./src/index.ts\",\n output: {\n filename: \"./dist/bundle.js\",\n },\n\n // Enable sourcemaps for debugging webpack's output.\n devtool: \"source-map\",\n\n resolve: {\n // Add '.ts' and '.tsx' as resolvable extensions.\n extensions: [\"\", \".webpack.js\", \".web.js\", \".ts\", \".tsx\", \".js\"]\n },\n\n module: {\n rules: [\n \n // All files with a '.ts' or '.tsx' extension will be handled by 'awesome-typescript-loader'.\n { test: /\\.tsx?$/, loader: \"awesome-typescript-loader\" },\n \n // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.\n { test: /\\.js$/, loader: \"source-map-loader\" }\n ]\n },\n\n // Other options...\n};
It’s important to note that awesome-typescript-loader will need to run before any other loader that deals with .js files.
The same goes for ts-loader, another TypeScript loader for Webpack.\nYou can read more about the differences between the two here.
\nYou can see an example of using Webpack in our tutorial on React and Webpack.
\nAt this point, you’re probably ready to start using TypeScript files.\nThe first step is to rename one of your .js files to .ts.\nIf your file uses JSX, you’ll need to rename it to .tsx.
Finished with that step?\nGreat!\nYou’ve successfully migrated a file from JavaScript to TypeScript!
\nOf course, that might not feel right.\nIf you open that file in an editor with TypeScript support (or if you run tsc --pretty), you might see red squiggles on certain lines.\nYou should think of these the same way you’d think of red squiggles in an editor like Microsoft Word.\nTypeScript will still translate your code, just like Word will still let you print your documents.
If that sounds too lax for you, you can tighten that behavior up.\nIf, for instance, you don’t want TypeScript to compile to JavaScript in the face of errors, you can use the noEmitOnError option.\nIn that sense, TypeScript has a dial on its strictness, and you can turn that knob up as high as you want.
If you plan on using the stricter settings that are available, it’s best to turn them on now (see Getting Stricter Checks below).\nFor instance, if you never want TypeScript to silently infer any for a type without you explicitly saying so, you can use noImplicitAny before you start modifying your files.\nWhile it might feel somewhat overwhelming, the long-term gains become apparent much more quickly.
Like we mentioned, it’s not unexpected to get error messages after conversion.\nThe important thing is to actually go one by one through these and decide how to deal with the errors.\nOften these will be legitimate bugs, but sometimes you’ll have to explain what you’re trying to do a little better to TypeScript.
\nYou might start out getting a bunch of errors like Cannot find name 'require'., and Cannot find name 'define'..\nIn these cases, it’s likely that you’re using modules.\nWhile you can just convince TypeScript that these exist by writing out
\nts// For Node/CommonJS\ndeclare function require(path: string): any;
or
\n\nts// For RequireJS/AMD\ndeclare function define(...args: any[]): any;
it’s better to get rid of those calls and use TypeScript syntax for imports.
\nFirst, you’ll need to enable some module system by setting TypeScript’s module flag.\nValid options are commonjs, amd, system, and umd.
If you had the following Node/CommonJS code:
\n\njsvar foo = require(\"foo\");\n\nfoo.doStuff();
or the following RequireJS/AMD code:
\n\njsdefine([\"foo\"], function(foo) {\n foo.doStuff();\n})
then you would write the following TypeScript code:
\n\ntsimport foo = require(\"foo\");\n\nfoo.doStuff();
If you started converting over to TypeScript imports, you’ll probably run into errors like Cannot find module 'foo'..\nThe issue here is that you likely don’t have declaration files to describe your library.\nLuckily this is pretty easy.\nIf TypeScript complains about a package like lodash, you can just write
\nshellnpm install -S @types/lodash
If you’re using a module option other than commonjs, you’ll need to set your moduleResolution option to node.
After that, you’ll be able to import lodash with no issues, and get accurate completions.
\nTypically, exporting from a module involves adding properties to a value like exports or module.exports.\nTypeScript allows you to use top-level export statements.\nFor instance, if you exported a function like so:
\njsmodule.exports.feedPets = function(pets) {\n // ...\n}
you could write that out as the following:
\n\ntsexport function feedPets(pets) {\n // ...\n}
Sometimes you’ll entirely overwrite the exports object.\nThis is a common pattern people use to make their modules immediately callable like in this snippet:
\n\njsvar express = require(\"express\");\nvar app = express();
You might have previously written that like so:
\n\njsfunction foo() {\n // ...\n}\nmodule.exports = foo;
In TypeScript, you can model this with the export = construct.
\ntsfunction foo() {\n // ...\n}\nexport = foo;
You’ll sometimes find yourself calling a function with too many/few arguments.\nTypically, this is a bug, but in some cases, you might have declared a function that uses the arguments object instead of writing out any parameters:
\njsfunction myCoolFunction() {\n if (arguments.length == 2 && !Array.isArray(arguments[1])) {\n var f = arguments[0];\n var arr = arguments[1];\n // ...\n }\n // ...\n}\n\nmyCoolFunction(function(x) { console.log(x) }, [1, 2, 3, 4]);\nmyCoolFunction(function(x) { console.log(x) }, 1, 2, 3, 4);
In this case, we need to use TypeScript to tell any of our callers about the ways myCoolFunction can be called using function overloads.
\ntsfunction myCoolFunction(f: (x: number) => void, nums: number[]): void;\nfunction myCoolFunction(f: (x: number) => void, ...nums: number[]): void;\nfunction myCoolFunction() {\n if (arguments.length == 2 && !Array.isArray(arguments[1])) {\n var f = arguments[0];\n var arr = arguments[1];\n // ...\n }\n // ...\n}
We added two overload signatures to myCoolFunction.\nThe first checks states that myCoolFunction takes a function (which takes a number), and then a list of numbers.\nThe second one says that it will take a function as well, and then uses a rest parameter (...nums) to state that any number of arguments after that need to be numbers.
Some people find it more aesthetically pleasing to create an object and add properties immediately after like so:
\n\njsvar options = {};\noptions.color = \"red\";\noptions.volume = 11;
TypeScript will say that you can’t assign to color and volume because it first figured out the type of options as {} which doesn’t have any properties.\nIf you instead moved the declarations into the object literal themselves, you’d get no errors:
\ntslet options = {\n color: \"red\",\n volume: 11\n};
You could also define the type of options and add a type assertion on the object literal.
\ntsinterface Options { color: string; volume: number }\n\nlet options = {} as Options;\noptions.color = \"red\";\noptions.volume = 11;
Alternatively, you can just say options has the type any which is the easiest thing to do, but which will benefit you the least.
any, Object, and {}You might be tempted to use Object or {} to say that a value can have any property on it because Object is, for most purposes, the most general type.\nHowever any is actually the type you want to use in those situations, since it’s the most flexible type.
For instance, if you have something that’s typed as Object you won’t be able to call methods like toLowerCase() on it.\nBeing more general usually means you can do less with a type, but any is special in that it is the most general type while still allowing you to do anything with it.\nThat means you can call it, construct it, access properties on it, etc.\nKeep in mind though, whenever you use any, you lose out on most of the error checking and editor support that TypeScript gives you.
If a decision ever comes down to Object and {}, you should prefer {}.\nWhile they are mostly the same, technically {} is a more general type than Object in certain esoteric cases.
TypeScript comes with certain checks to give you more safety and analysis of your program.\nOnce you’ve converted your codebase to TypeScript, you can start enabling these checks for greater safety.
\nanyThere are certain cases where TypeScript can’t figure out what certain types should be.\nTo be as lenient as possible, it will decide to use the type any in its place.\nWhile this is great for migration, using any means that you’re not getting any type safety, and you won’t get the same tooling support you’d get elsewhere.\nYou can tell TypeScript to flag these locations down and give an error with the noImplicitAny option.
null & undefined ChecksBy default, TypeScript assumes that null and undefined are in the domain of every type.\nThat means anything declared with the type number could be null or undefined.\nSince null and undefined are such a frequent source of bugs in JavaScript and TypeScript, TypeScript has the strictNullChecks option to spare you the stress of worrying about these issues.
When strictNullChecks is enabled, null and undefined get their own types called null and undefined respectively.\nWhenever anything is possibly null, you can use a union type with the original type.\nSo for instance, if something could be a number or null, you’d write the type out as number | null.
If you ever have a value that TypeScript thinks is possibly null/undefined, but you know better, you can use the postfix ! operator to tell it otherwise.
\ntsdeclare var foo: string[] | null;\n\nfoo.length; // error - 'foo' is possibly 'null'\n\nfoo!.length; // okay - 'foo!' just has type 'string[]'
As a heads up, when using strictNullChecks, your dependencies may need to be updated to use strictNullChecks as well.
any for thisWhen you use the this keyword outside of classes, it has the type any by default.\nFor instance, imagine a Point class, and imagine a function that we wish to add as a method:
\ntsclass Point {\n constructor(public x, public y) {}\n getDistance(p: Point) {\n let dx = p.x - this.x;\n let dy = p.y - this.y;\n return Math.sqrt(dx ** 2 + dy ** 2);\n }\n}\n// ...\n\n// Reopen the interface.\ninterface Point {\n distanceFromOrigin(point: Point): number;\n}\nPoint.prototype.distanceFromOrigin = function(point: Point) {\n return this.getDistance({ x: 0, y: 0});\n}
This has the same problems we mentioned above - we could easily have misspelled getDistance and not gotten an error.\nFor this reason, TypeScript has the noImplicitThis option.\nWhen that option is set, TypeScript will issue an error when this is used without an explicit (or inferred) type.\nThe fix is to use a this-parameter to give an explicit type in the interface or in the function itself:
","headings":[{"value":"Setting up your Directories","depth":1},{"value":"Writing a Configuration File","depth":1},{"value":"Early Benefits","depth":2},{"value":"Integrating with Build Tools","depth":1},{"value":"Gulp","depth":2},{"value":"Webpack","depth":2},{"value":"Moving to TypeScript Files","depth":1},{"value":"Weeding out Errors","depth":2},{"value":"Importing from Modules","depth":3},{"value":"Getting Declaration Files","depth":3},{"value":"Exporting from Modules","depth":3},{"value":"Too many/too few arguments","depth":3},{"value":"Sequentially Added Properties","depth":3},{"value":"any, Object, and {}","depth":3},{"value":"Getting Stricter Checks","depth":2},{"value":"No Implicit any","depth":3},{"value":"Strict null & undefined Checks","depth":3},{"value":"No Implicit any for this","depth":3}],"frontmatter":{"permalink":"/docs/handbook/migrating-from-javascript.html","title":"Migrating from JavaScript"}}},"pageContext":{"slug":"/docs/handbook/migrating-from-javascript.html","isOldHandbook":true}}}tsPoint.prototype.distanceFromOrigin = function(this: Point, point: Point) {\n return this.getDistance({ x: 0, y: 0});\n}