One of the best things about Node.js is its massive module ecosystem. With bundlers like webpack we can leverage these even in the browser outside of Node.js. Let’s look at how we can build a module with TypeScript usable by both JavaScript developers and TypeScript developers.
Before we get started make sure that you have Node.js installed – you should ideally have a version of 6.11 or higher. Additionally make sure that you have npm or a similar package manager installed.
Let’s build a module that exposes a function that filters out all emojis in a string and returns the list of emoji shortcodes. Because who doesn’t love emojis?
✨ Installing dependencies
First create a new directory for your module and initialize the package.json
by running in your command line:
mkdir emoji-search
cd emoji-search
npm init -y
The resulting package.json
looks like this:
{
"name": "emoji-search",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Now let’s install some dependencies. First install the TypeScript compiler as a devDependency
by running:
npm install typescript --save-dev
Next install the emojione
module. We’ll use this to convert emojis to their shortcodes like 🵠to :monkey_face:
. Because we will be using the module in TypeScript and the module doesn’t expose the types directly we also need to install the types for emojione
:
npm install emojione @types/emojione --save
With the project dependencies installed we can move on to configuring our TypeScript project.
🔧 Configuring the TypeScript project
Start by creating a tsconfig.json
file which we’ll use to define our TypeScript compiler options. You can create this file manually and place the following lines into it:
{
"compilerOptions": {
"target": "es5",
"module": "commonjs",
"declaration": true,
"outDir": "./dist",
"strict": true
}
}
Alternatively you can auto-generate the tsconfig.json
file with all available options by running:
./node_modules/.bin/tsc --init
If you decided for this approach just make sure to adjust the declaration
and outDir
options according to the JSON above.
Setting the declaration
attribute to true
ensures that the compiler generates the respective TypeScript definitions files aside of compiling the TypeScript files to JavaScript files. The outDir
parameter defines the output directory as the dist
folder.
Next modify the package.json
to have a build script that builds our code:
{
"name": "emoji-search",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"typescript": "^2.3.2"
},
"dependencies": {
"@types/emojione": "^2.2.1",
"emojione": "^3.0.3"
}
}
That’s all we have to do to configure the TypeScript project. Let’s move on to writing some module code!
💻 Create the module code
Create a lib
folder where we can place all of our TypeScript files and in it create a create a file called index.ts
. Place the following TypeScript into it:
import { toShort } from 'emojione';
const EMOJI_SHORTCODES = /:[a-zA-Z1-9_]+:/g
export function findEmojis(str: string): string[] {
// add runtime check for use in JavaScript
if (typeof str !== 'string') {
return [];
}
return toShort(str).match(EMOJI_SHORTCODES) || [];
}
Compile the code by running:
npm run build
You should see a new dist
directory that has two files, index.js
and index.d.ts
. The index.js
contains all the logic that we coded compiled to JavaScript and index.d.ts
is the file that describes the types of our module for use in TypeScript.
Congratulations on creating your first module accessible to both TypeScript and Javascript! Lets prep the module for publishing.
🔖 Prepare for publishing
Now that we have our module, we have to make three easy changes to the package.json
to get ready to publish the module.
- Change the
main
attribute to point at our generated JavaScript file - Add the new
types
parameter and point it to the generated TypeScript types file - Add a
prepublish
script to make sure that the code will be compiled before we publish the project.
{
"name": "emoji-search",
"version": "1.0.0",
"description": "",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
"prepublish": "npm run build",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"typescript": "^2.3.2"
},
"dependencies": {
"@types/emojione": "^2.2.1",
"emojione": "^3.0.3"
}
}
We should also make sure to exclude unnecessary files from the installation of our module. In our case the lib/
folder is unnecessary because we only need the built files in the dist/
directory. Create a new file called .npmignore and place the following content into it:
lib/
That’s it! 🎉 You are ready now to publish your module using npm publish
. Unfortunately someone already built a module called emoji-search
😕 so if you want to publish this module, just change the name in the package.json
to another name.
🽠Consume the module
The great thing with our module is that this can now be seamlessly used in JavaScript or TypeScript projects. Simply install it via npm
or yarn
:
npm install emoji-search --save
If you want to try this out without publishing the module yourself you can also install the demo-emoji-search
module. It is the same code published on npm. Afterwards we can use the module in JavaScript:
const emojiSearch = require('demo-emoji-search');
console.log(emojiSearch.findEmojis("Hello ðŸ¼! What's up? ✌ï¸"));
Or in TypeScript with full type support:
import { findEmojis } from 'demo-emoji-search';
const foundEmojis: string[] = findEmojis(`Hello ðŸµ! What's up? ✌ï¸`);
console.log(foundEmojis);
🎊 Conclusion
Now this was obviously just a very simple module to show you how easy it is to publish a module usable in both Javascript and TypeScript.
There are a boatload of other benefits provided by TypeScript to the author of the module such as:
- Better authoring experience through better autocomplete
- Type safety to catch bugs especially in edge cases early
- Down-transpilation of cutting-edge and experimental features such as decorators
As you’ve seen it’s very easy to build a module in TypeScript to provide a kickass experience with our module to both JavaScript and TypeScript developers. If you would like to have a more comprehensive starter template to work off that includes a set of best practices and tools, check out Martin Hochel’s typescript-lib-starter on GitHub.
âœŒï¸ I would love to hear about your experience with TypeScript and feel free to reach out if you have any problems:
- 📧 Email: dkundel@twilio.com
- 🦠Twitter: @dkundel
- 🖥 GitHub: dkundel
Writing a Node.js module in TypeScript was originally published on the Twilio Blog on June 8, 2017.
Top comments (8)
Watch out –
prepublish
is deprecated: docs.npmjs.com/misc/scripts#deprec...Should
@types/emojione
be dev dependency?prepublish
itself is not deprecated. The old behavior is deprecated. But it's not the behavior that I'm intending here.No the
@types/emojione
should be a normal dependency because it's a dependency of the generated.d.ts
file. Basically the@types
of any regular dependency should also be a regular dependency.prepublish
: right. npm’s deprecation warning gave me the wrong impression. I’m usingprepublishOnly
to avoid that warning, but it looks like that will be deprecated in the long run, whileprepublish
will stay (withprepublishOnly
behavior): github.com/npm/npm/issues/10074@types/emojione
: make sense, didn’t know about dependencies between type definition files.In this case it doesn't make a difference whether
@types/emojione
is a dev dependency or not because the.d.ts
will only expose one signature that has only built-in types. But if we would have a function that for example exposes aBuffer
as part of one signature and we would need@types/node
as a normal dependency since the generated.d.ts
file has a connection to it. So the best practice would be to just do it for all dependencies that you actually use during runtime.There's an error in your regex string. It should be
var EMOJI_SHORTCODES = /:[a-zA-Z1-9_]+:/g;
You've forgotten the
+
at the end of the[]
Ah it was dropped during the import from the other blog. Thank you!
Your last code example has one to many ( in it
findEmojis((
Hello 🐵! What's up? ✌️
);Good catch! thanks!