Minimal demo showing how to use TypeScript with node.js/npm modules
In the minimalistic example app we use the xregexp module to execute a simple RegExp on a string an log the output, and a local module to show relative imports.
This is a very simple example to show the essentials.
The typings are from DefinitelyTyped.
Have node.js installed, it comes with the npm
package manager.
Have the global tsc
TypeScript compiler:
npm install typescript -g
Clone the repos to your local workspace
Use your command-line:
A) From package.json
(recommended for existing projects):
npm install
B) Manually (when adding new modules)
npm install xregexp --save
This will create the node_modules
and add the xregexp
package. If you look into the node_modules/xregexp
folder you see a lot of stuff, but we don't have to be aware of any of that:
The magic happens when node loads a module: it will scan the node_modules
folder and find the xregexp
folder. In the package.json
it will see the element "main": "./xregexp-all.js"
.
This tells node that the xregexp
module uses that file as main-entry point. This also means you don't have to look into the folder as module resolution is all automated.
See http://nodejs.org/api/modules.html#modules_loading_from_node_modules_folders for the actual logic (it is very clever).
It contains a folder xregexp
with a file xregexp.d.ts
. These names are not 'magic'. You have to explicitly reference them using a /// <reference ..
tag in your code.
This particular typing defines a xregexp
external module (notice the name matches the npm module's name)
Note the /// <reference ..
tag, it is a relative path from this file to the typing .d.ts
. It will add all it's content to the compilers namespace but not do anything on its own.
Note the import x = require('xregexp')
. This serves two purposes:
- At compile time TypeScript will use it to attach type information, it expects to have type declaration for a
xregexp
module (this is why we had the reference mentioned above). 2 - At runtime it becomes the actual module import, it will use node's standard
require
system to get thexregexp
module from thenode_modules
folder.
Note the import g = require('./lib/greeter');
This will import our own TypeScript module. When we compile the index.ts
the compiler will also compile this sub module to it's own JavaScript file.
We will compile index.ts
to index.js
Every file it imports
automatically gets compiled to it's own module too.
Because we're on node and using import
we will generate CommonJS modules:
tsc index.ts --module commonjs
Open the index.js
and ./lib/greeter.js
. Because TypeScript is mostly syntax sugar this looks very similar to the source-code.
Notice how the import
's are transformed in a plain var
assignment.
The require
's still have the same values. One has the npm module name and will be resolved by node, the other has the relative path to our own module.
node ./index.js
It will run the code, in our case we see the output from the console in the example code (a simple RegExp result and a greeting).
- Add more modules, both from npm as well as your own.
- Define your own typing for a module. Look at the pattern in the example or visit the guide on DefinitelyTyped.
- Use TSD to pull definitions from DefinitelyTyped and work with the
tsd.d.ts
bundle to manage your references.
Fixes and clarifications are very welcome. Send a pull request or leave a ticket if you found any problems.
Copyright (c) 2014 DefinitelyTyped
Licensed under the MIT license.