What is typescript file

Files

Out of the box, the TypeScript compiler can understand TypeScript files ( *.ts ) and TypeScript declaration files (aka typings files, *.d.ts ). Optionally, it can understand TypeScript React files ( *.tsx ) and JavaScript files ( *.js )

But do you know that each of them can also be categorized as either a «script file» or a «module file»?

TypeScript file

Doesn’t need much explanation. When you name your file with .ts extension, your IDE and compiler will treat it as TypeScript file.

TypeScript declaration file

TypeScript declaration files are used to describe the «typings» of some JavaScript libraries. They are the files created in DefinitelyTyped or Repositories referenced in typings registry.

They are «amibent» in nature, meaning it does not contain any actual implementation code.

The formal term for these files is «file with ambient module declaration». You will see why in a moment.

Script file

Script files are files that do not have any top level import / export declaration. Sometimes they are also called as «global files» because they are global in nature. For example, the following script file will create a global variable window.Foo in browser environment:

namespace Foo < export const SOMETHING = 1; >; 

Thus TypeScript files or declaration files written in this form could be described as «script file» or «script file wtih ambient module declaration»

Module file

Module files are files that has one or more top level import / export declaration. Being a module file means its content is not global, and it is align with what a module means in ECMAScript.

Thus TypeScript files or declaration files written in this form could be described as «module file» or «module file wtih ambient module declaration»

Источник

How does TypeScript work? The bird’s eye view

This blog post gives the bird’s eye view of how TypeScript works: What is the structure of a typical TypeScript project? What is compiled and how? How can we use IDEs to write TypeScript?

This post is meant to be read before learning how to write TypeScript code (material for doing that is listed at the end).

The structure of TypeScript projects #

This is one possible file structure for TypeScript projects:

typescript-project/ dist/ ts/ src/ main.ts util.ts test/ util_test.ts tsconfig.json 

• Directory ts/ contains the TypeScript files:
  • Subdirectory ts/src/ contains the actual code.
  • Subdirectory ts/test/ contains tests for the code.

  tsconfig.json #

  The contents of tsconfig.json look as follows:

   "compilerOptions":  "rootDir": "ts", "outDir": "dist", "module": "commonjs", ··· > > 

  • The root directory of the TypeScript code is ts/ .
  • The directory where the TypeScript compiler saves its output is dist/ .
  • The module format of the output files is CommonJS.

  Programming TypeScript via an integrated development environment (IDE) #

  Visual Studio Code is one of the most popular IDEs for writing TypeScript code. In order to use it well, we need to understand that TypeScript source code is processed in two independent ways:

  • Checking open editors for errors: This is done via a so-called language server. They are an editor-independent way of providing editors with language-related services (detecting errors, refactorings, auto-completions, etc.). Editors (such as IDEs) communicate with language servers via a special protocol (JSON-RPC, i.e. JSON-based remote procedure calls). That enables one to write such servers in almost any programming language.
    • Important fact to remember: The language server only lists errors for currently open editors and it doesn’t compile TypeScript, it only analyzes it statically.
    • We can run a build tool via a command line. For example, the TypeScript compiler tsc has a —watch mode that watches input files and compiles them to output files whenever they change. As a consequence, whenever we save a TypeScript file in the IDE, we immediately get the corresponding output file(s).
    • We can run tsc from within Visual Studio Code. In order to do so, it must be installed either inside project that we are currently working on or globally (via the Node.js package manager npm).

    With building, we get a complete list of errors. For more information on compiling TypeScript in Visual Studio Code, see the official documentation for that IDE.

    Other files produced by the TypeScript compiler #

    Given a TypeScript file main.ts , the TypeScript compiler can produce several kinds of artifacts. The most common ones are:

    • JavaScript file: main.js
    • Declaration file: main.d.ts (contains type information; think .ts file minus the JavaScript code)
    • Source map file: main.js.map

    TypeScript is often not delivered via .ts files, but via .js files and .d.ts files:

    • The JavaScript code contains the actual functionality and can be consumed via plain JavaScript.
    • The declaration files help programming editors with auto-completion and similar services. This information enables plain JavaScript to be used via TypeScript. However, we even profit from it if we work with plain JavaScript because it gives us better auto-completion and more.

    A source map specifies for each part of the output code in main.js , which part of the input code in main.ts produced it. Among other things, this information enables runtime environments to execute JavaScript code, while showing the line numbers of the TypeScript code in error messages.

    In order to use npm packages from TypeScript, we need type information #

    The npm registry is a huge repository of JavaScript code. If we want to use a JavaScript package from TypeScript, we need type information for it:

    • The package itself may include .d.ts files or even the complete TypeScript code.
    • If it doesn’t, we may still be able to use it: DefinitelyTyped is a repository of declaration files that people have written for plain JavaScript packages.

    The declaration files of DefinitelyTyped reside in the @types namespace. Therefore, if we need a declaration file for a package such as lodash , we have to install the package @types/lodash .

    Using the TypeScript compiler for plain JavaScript files #

    The TypeScript compiler can also process plain JavaScript files:

    • With the option —allowJs , the TypeScript compiler copies JavaScript files in the input directory over to the output directory. Benefit: When migrating from JavaScript to TypeScript we can start with a mix of JavaScript and TypeScript files and slowly convert more JavaScript files to TypeScript.
    • With the option —checkJs , the compiler additionally type-checks JavaScript files ( —allowJs must be on for this option to work). It does so as well as it can, given the limited information that is available.
      • If a JavaScript file contains the comment // @ts-nocheck , it will not be type-checked.
      • Without —checkJs , the comment // @ts-check can be used to type-check individual JavaScript files.

      This is an example of a JSDoc comment that provides static type information for a function add() :

      /** * @param number> x - A number param. * @param number> y - A number param. * @returns number> This is the result */ function add(x, y) < return x + y; > 

      More information: Type-Checking JavaScript Files in the TypeScript Handbook.

      What to read next #

      Источник