The most common Typescript definition files for meteor, including meteor.d.ts
TypeScript JavaScript

README.md

Meteor TypeScript libraries -- deprecated

Deprecated

This package is now deprecated, and these definitions are no longer maintained. However, these definitions should work up to Meteor version 1.2.1.

The most up-to-date definitions for Meteor 1.2 and beyond can now be found using the NPM Typings definition manager. Here are the meteor definitions referenced by that tool: https://github.com/meteor-typings.

Also, there is currently an effort supported by the Meteor Development Group to create a TypeScript build compiler package, and an early version of the package can be tested using barbatus:typescript. This package will eventually incorporated as a Meteor core package (e.g. like the coffeescript package). It appears that the recommended practice for adding definitions using that package will be to add them using the typings tool.

You can follow discussion about this effort here.

Description

This project adds TypeScript definition files related to Meteor. It includes meteor.d.ts plus many others. Although these definitions were created using the Meteor 1.3 docs, they lack definitions for the ES6 modules now supported by Meteor version 1.3 and later. These definitions require TypeScript 1.8 or higher (to allow for string literal types). These definitions are mostly backwards compatible for any 1.* Meteor version.

Why use TypeScript?

TypeScript is a supserset of JavaScript that enforces relaxed static typing and compiles to plain Javascript. It offers most of the benefits of a strongly typed language without requiring you to use strong typing.

In general, TypeScript will NOT make JavaScript prettier (like CoffeeScript). However, it can help simplify JavaScript programming for the many object oriented coders out there. TypeScript also provides transparent access to features only available in ECMAScript 7 and above.

For further reading about TypeScript, please refer to the TypeScript Handbook.

Usage

Setup (OSX/Linux)

  1. Add a symbolic link to the definitions from within some directory within your project (e.g. ".typescript" or "lib"). The definitions can be found somewhere deep within <project_root_dir>/.meteor/.... The following will probably work:

    $ ln -s ../.meteor/local/build/programs/server/assets/packages/meteortypescript_typescript-libs/definitions package_defs
    

    If the definitions can't be found within the .meteor directory, you will have to manually pull down the definitions from github and add them to your project:

    https://github.com/meteor-typescript/meteor-typescript-libs

  2. Install the Typescript compiler for Meteor or an IDE which can transpile TypeScript to JavaScript.

Setup (Windows)

  1. Typed definitions will be present following a fresh build of meteor at the path: <project_root>/.meteor/local/build/programs/server/assets/packages/meteortypescript_typescript-libs/definitions

    If the definitions can't be found within the .meteor directory, you will have to manually pull down the definitions from github and add them to your project:

    Alternatively, you may find using tsd more flexible than adding typings via meteor. Typings for meteor-typescript files are availble via the command:

    tsd install meteor --save
    
  2. A symbolic link may be created for this directory via the cmd:

    mklink /d .typings .meteor/local/build/programs/server/assets/packages/meteortypescript_typescript-libs/definitions
    

Compiler and Referencing

  1. Install the Typescript compiler for Meteor or an IDE which can transpile TypeScript to JavaScript
  2. From the typescript files, add references. Reference the definition files with a single line:

    /// <reference path=".typescript/package_defs/all-definitions.d.ts" />  (substitute path in your project)
    

    Or you can reference definition files individually:

    /// <reference path=".typescript/package_defs/meteor.d.ts" />  (substitute path in your project)
    /// <reference path=".typescript/package_defs/underscore.d.ts" />
    /// <reference path=".typescript/package_defs/jquery.d.ts" />
    

    Meteor core definitions can be referenced in an "all-in-one" definition file ( meteor.d.ts ) or definition files specific to the locus of execution:

    • meteor.d.ts: all meteor core definitions
    • meteor.common.d.ts: meteor core code running on both client and server
    • meteor.client.d.ts: meteor core client-only code
    • meteor.server.d.ts: meteor core server-only code
    • meteor.package.d.ts: meteor core package-only code
    • meteor.build.d.ts: meteor core build-only code

    meteor.d.ts contains all of the definitions found in meteor.common.d.ts, meteor.client.d.ts, meteor.server.d.ts, meteor.package.d.ts, and meteor.build.d.ts

  3. Be aware of differences in coding styles when using TypeScript (see below)

TypeScript/Meteor coding style

References

Meteor code can run on the client and the server, for this reason you should try to stay away from referencing file.ts directly: you may get unexpected results.

Rather generate a file.d.ts using tsc --declaration file.ts, and reference it in your file.

Compilation will be much faster and code will be cleaner - it's always better to split definition from implementation anyways.

Templates

With the exception of the body and head templates, Meteor's Template dot notation cannot be used (ie. Template.mytemplate). Thanks to Typescript static typing checks, you will need to use the bracket notation to access the Template.

Template['myTemplateName'].helpers({
  foo: function () {
    return Session.get("foo");
  }
});

Template['myTemplateName'].onRendered(function ( ) { ... });

The same is true for Meteor.settings:

Meteor.settings.public['<some config>']    

Form fields

Form fields typically need to be cast to <HTMLInputElement>. For instance to read a form field value, use (<HTMLInputElement>evt.target).value.

Global variables

Preface any global variable declarations with a TypeScript "declare var" statement (or place the statement in a definition file):

declare var NavbarHelpers;
NavbarHelpers = {};
NavbarHelpers.someMethod = function() {...}

Collections

The majority of extra work required to use TypeScript with Meteor is creating and maintaining the collection interfaces. However, doing so also provides the additional benefit of succinctly documenting collection schema definitions (that are actually enforced).

To define collections, you will need to create an interface representing the collection and then declare a Collection type variable with that interface type (as a generic):

interface JobDAO {
  _id?: string;
  name: string;
  status?: string;
  queuedAt?: string;
}

declare var Jobs: Mongo.Collection<JobDAO>;
Jobs = new Mongo.Collection<JobDAO>('jobs');

Finally, any TypeScript file using collections will need to contain a reference at the top pointing to the collection definitions:

/// <reference path=".typescript/package_defs/meteor.d.ts"/>
/// <reference path=".typescript/custom_defs/collections.ts"/>

Creating definition files

Here is a guide to creating definitions: http://www.typescriptlang.org/Handbook#writing-dts-files

If you have lots of custom definitions for a project, you can:

  • Create multiple definition files and include individual references to each definition file.
  • Create one huge monolithic definition file so you only have to refer to that file.
  • Create multiple definition files, and create a definition file with references to the other definitions files so that you only have to maintain one reference for all of you custom definitions. e.g. contents of ".typescript/custom_defs/custom-definitions.d.ts":

    /// <reference path='collections.ts' />
    /// <reference path='paraview_helpers.d.ts'/>
    /// <reference path='handsontable.d.ts'/>
    /// <reference path='utility_helpers.ts'/>
    

Transpiling TypeScript

Meteor plugin

One solution for transpiling typescript is to install the following meteor package: https://github.com/meteor-typescript/meteor-typescript-compiler

IDE/Editor Transpilation

WebStorm, SublimeText, Atom, and VisualStudio all support TypeScript. They can automatically transpile your TypeScript code into JavaScript every time you save a file.

WebStorm

To support TypeScript in WebStorm on OSX, first install the TypeScript transpiler on your system:

$ [sudo -H] npm install -g typescript

On version 10 of WebStorm or later, got to Preferences -> Languages & Frameworks -> TypeScript and check "Enable TypeScript Compiler"

On older versions of WebStorm (9 or earlier), go to Preferences -> File Watchers -> "+" symbol and add TypeScript.

SublimeText, Atom, and VisualStudio

Please refer to the documentation for these editors.

Command line

The last option is to compile code from the command line. With node and the TypeScript compiler installed:

$ tsc *.ts

Contributing

Please improve the meteor definitions for the Typings definition manager instead of the definitions in this package.

Creating meteor.d.ts and its related files

All definition files in this Meteor package are generated by executing the makefile (depends on npm):

$ make

The makefile generates meteor.d.ts, meteor.common.d.ts, meteor.client.d.ts, meteor.server.d.ts, meteor.package.d.ts, and meteor.package.d.ts from the same Meteor data.js file that is used to generate the official Meteor docs.

This script also retrieves the latest third-party library definitions from the DefinitelyTyped repo, which is the semi-official repository for TypeScript definition files. Running this script will also run any specified tests found on DefinitelyTyped as well as the tests for meteor.d.ts and any other meteor packages. All tests that are run can be found in "script-definition-tests/".

Finally, this script creates package.js and ./definitions/all-definitions.d.ts with file lists of the definition files found in the ./definitions directory.

Creating Definitions

Writing typed definition files takes practice and experimentation, please refer to this guide for more details.