DevTut

# Importing external libraries

# Finding definition files

for typescript 2.x:

definitions from DefinitelyTyped (opens new window) are available via @types npm (opens new window) package

npm i --save lodash
npm i --save-dev @types/lodash

but in case if you want use types from other repos then can be used old way:

for typescript 1.x:

Typings (opens new window) is an npm package that can automatically install type definition files into a local project. I recommend that you read the quickstart (opens new window).

npm install -global typings

Now we have access to the typings cli.

  • The first step is to search for the package used by the project 
    typings search lodash
NAME              SOURCE HOMEPAGE                                        DESCRIPTION VERSIONS UPDATED
lodash            dt     http://lodash.com/                                          2        2016-07-20T00:13:09.000Z
lodash            global                                                             1        2016-07-01T20:51:07.000Z
lodash            npm    https://www.npmjs.com/package/lodash                        1        2016-07-01T20:51:07.000Z
  • Then decide which source you should install from. I use dt which stands for [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) a GitHub repo where the community can edit typings, it's also normally the most recently updated.
  • Install the typings files 
     typings install dt~lodash --global --save

    • Let's break down the last command. We are installing the DefinitelyTyped version of lodash as a global typings file in our project and saving it as a dependency in the typings.json. Now wherever we import lodash, typescript will load the lodash typings file.

  • If we want to install typings that will be used for development environment only, we can supply the `--save-dev` flag: 
     typings install chai --save-dev

    • # Importing a module from npm

    If you have a type definition file (d.ts) for the module, you can use an import statement.

    import _ = require('lodash');

    If you don't have a definition file for the module, TypeScript will throw an error on compilation because it cannot find the module you are trying to import.

    In this case, you can import the module with the normal runtime require function. This returns it as the any type, however.

    // The _ variable is of type any, so TypeScript will not perform any type checking.
const _: any = require('lodash');

    As of TypeScript 2.0, you can also use a shorthand ambient module declaration in order to tell TypeScript that a module exists when you don't have a type definition file for the module. TypeScript won't be able to provide any meaningful typechecking in this case though.

    declare module "lodash";

// you can now import from lodash in any way you wish:
import { flatten } from "lodash";
import * as _ from "lodash";

    As of TypeScript 2.1, the rules have been relaxed even further. Now, as long as a module exists in your node_modules directory, TypeScript will allow you to import it, even with no module declaration anywhere. (Note that if using the --noImplicitAny compiler option, the below will still generate a warning.)

    // Will work if `node_modules/someModule/index.js` exists, or if `node_modules/someModule/package.json` has a valid "main" entry point
import { foo } from "someModule";

    # Using global external libraries without typings

    Although modules are ideal, if the library you are using is referenced by a global variable (like $ or _), because it was loaded by a script tag, you can create an ambient declaration in order to refer to it:

    declare const _: any;

    # Finding definition files with typescript 2.x

    With the 2.x versions of typescript, typings are now available from the npm @types repository (opens new window). These are automatically resolved by the typescript compiler and are much simpler to use.

    To install a type definition you simply install it as a dev dependency in your projects package.json

    e.g.

    npm i -S lodash
npm i -D @types/lodash

    after install you simply use the module as before

    import * as _ from 'lodash'

    # Syntax

    • import {component} from 'libName'; // Will import the class "component"
    • import {component as c} from 'libName'; // Will import the class "component" into a "c" object
    • import component from 'libname'; // Will import the default export from libName
    • import * as lib from 'libName'; // Will import everything from libName into a "lib" object
    • import lib = require('libName'); // Will import everything from libName into a "lib" object
    • const lib: any = require('libName'); // Will import everything from libName into a "lib" object
    • import 'libName'; // Will import libName module for its side effects only

    # Remarks

    It might seem that the syntax

    import * as lib from 'libName';

    and

    import lib = require('libName');

    are the same thing, but they are not!

    Let us consider that we want to import a class Person exported with TypeScript-specific export = syntax :

    class Person {
...
}
export = Person;

    In this case it is not possible to import it with es6 syntax (we would get an error at compile time), TypeScript-specific import = syntax must be used.

    import * as Person from 'Person';  //compile error
import Person = require('Person');  //OK

    The converse is true: classic modules can be imported with the second syntax, so, in a way, the last syntax is more powerful since it is able to import all exports.

    For more information see the official documentation (opens new window).

    ← Modules - exporting and importing →