Properly deploying typescript libraries using require.js

Like many of you I spent hours finding a good solution to a very common problem: how to properly deploy my typescript libraries. We will focus on how to deploy, structure and use our self made libraries. We will be using require.js as our module loader and r.js as our build tool. While we will be using Microsoft’s TypeScript these tools and principles are all compatible with vanilla javascript as well.

Why require.js and r.js?

Require.js is one of my favorite tools for java script development. It enables you to debug and deploy your code a lot faster while developing.
Like it’s more famous counter parts grunt and gulp, r.js is a build tool. It let’s you minify all of your separate files of code into a single file for deployment. You can use it to mangle all of your code to make it harder to read for the people who shouldn’t be looking. It can even include other libraries like jQuery into your project.

Install require.js and typings

There are multiple ways to install require.js. You can get the files manually or use a package manager to download them with a command. I’m using nuget commands since I do most of my work in Visual Studio. You’ll need two files: the typings and the library.

Install-Package RequireJS
Install-Package requirejs.TypeScript.DefinitelyTyped
Install-Package almond

We are using almond to include a more lightweight module loader in our library so the user isn’t bothered with providing one themselves.

You will also need to download and install Node.js with NPM to be able to use the r.js build tool.

Just a few functions and files

I’ll start by setting up a few files. These files will demonstrate how to allow access to the functions we want the user to be able to access. Let’s go ahead and put them in a folder called app.

This is our main file. It is the main entry point for our app and it determines what we want to expose and what we don’t. It’s also the file that determines what gets imported and what doesn’t.

This is our utility file. Just something simple to illustrate how require will include all of our imported files through our main file.

Configuring require and running our project

With this file we can tell require all that it needs to know to run our project without having to deploy it.

The base Url tells require where our base folder is located. You’ll see we’re referencing jQuery but we’re actually not using it. But seeing as you’ll probably be using this or some other library I included it regardless. The paths tell require where it can find the library and can create an alias for easier usage in the process. The shim lets us group the multiple exports jQuery does under the familiar ‘$’. Now the import we did in our main.ts file will actually work.

Now we just have to add it to our HTML page. You can do that by adding this simple tag.

BAM! That’s it, you should now be able to run your project!

Now let’s start building

Now let’s get to the part that you came here for. To build our project we need to set up three more files. I prefer to put files like this in a special build folder that I put next to my app folder.

This file will tell our build tool, r.js, what to build and how to build it.

name: our main entry point
mainConfigFile: our require configuration
out: path and name for the result
wrap: some javascript code we will wrap our result with so we can use the result as a library
include: a library we want to include in our output that require would otherwise not find because we don’t reference it in our project files

We will use this file to tell the outside world what name our library will respond to. In this case we will just call it ‘lib’.

This file will be used to tell our library which file is the main file. In this case it’s the main file located in the app folder.

Building and deploying

Open a command prompt and navigate to the folder you installed require to. Then use this command to build your project.
node r.js -o build/build.js

Now you have to replace the tag that you used earlier in your html page with the following.

Notice that you won’t have to reference require.js anymore because we included almond into our library!

And now to test our library add this piece of code to your body in your html file.

That’s it! Feel free to check out our products, company or our other posts!