Sunday, May 3, 2015

Visual Studio Code for Mac | Angular TypeScript Yeoman Setup

Example code for this post can be found on GitHub.

Visual Studio Code on Mac OS X is awesome. In fact, Visual Studio Code is awesome period. I have been using Brackets on OS X for a while now as a free alternative to Sublime. Brackets is good, but I am a Visual Studio junkie in Windows and having Visual Studio in OS X to do front end (angular) and back end (C# / web api) development is just awesome.

To get started with Visual Studio Code on my Mac, I decided to create a new project (Angular, TypeScript, Bootstrap) scaffolded by Yeoman. I want to use Angular as the base front end framework, use TypeScript for all of the front end code, use Bootstrap for responsive rendering and use John Papa's style guide for Angular structure. I figured a lot of people are going to go down the same path, so I might as well share the recipe.

Pre-req app installs

Download and install nodejs Lightweight web server that includes npm, which we will use a lot.

Download and install Git version control client

Download and install mono Cross platform .NET framework, not really a pre-req for pure front end work, but you will need this if you open a Visual Studio project in Visual Studio Code on Mac OS X.

Download and install Visual Studio Code for Mac OS X

Install global npm packages

We will use Node Package Manager (npm) to download and install all of the required packages that will give us a rich front end development environment where we can write code, buid and test with ease. The npm -g option installs packages globally. You only want to use this option for packages that you want to be available across your operating system.

We want to install bower (front end package manager), grunt-cli (task runner/build command line interface), yeoman (scaffolding tool), karma (angular test runner), typescript (type superset for javascript), tsd (definitelyTyped definitions for TypeScript intellisense) and a yeoman generator for angular projects. It makes sense to install all of these globally as they are generally applicable tools for any front end app.

Open an OS X Terminal

Run the following command

$sudo npm install -g bower grunt-cli yo karma jasmine typescript tsd@next generator-angular generator-karma

(sudo will elevate the command to run with administrative privileges and will require your password)

Scaffold and install project packages

Create a directory for your new project

$mkdir ~/Documents/Source/Repos/VsCodeAngularTypeScript

cd into your project directory

$cd ~/Documents/Source/Repos/VsCodeAngularTypeScript/

Run the following commands

$yo angular YourAppNameGoesHere

(yeoman will scaffold a new angular project for you, choose the angular dependencies you want to use)

$grunt serve

This should build the scaffolded angular project, launch a new nodejs server and serve up index.html If you get errors as this point, see what you missed in the previous steps and fix them before proceeding further.

You should see this page pop up in your browser:

Now let's setup TypeScript and TypeScript intellisense for our new project.

Run the following commands: (note we are using the —-save option on all commands to add references to the npm and tsd package configs so they can be easily restored later)

$tsd install jquery --save

(installs jquery TypeScript definition file to typings/jquery and creates/adds the reference in tsd.json - this is a dependency of angular TypeScript definition)

$tsd install angular --save

(installs angular TypeScript definition file to typings/angular and adds a reference in tsd.json)

After the two tsd commands are executed, you will see a few things appear in your project:

  • tsd.json in your root folder
  • typings folder in root
  • typings/tsd.d.ts
  • typings/jquery and typings/angular

The /typings folder contains all of the TypeScript definition files that will be used to generated Intellisense. The /typings folder also contains tsd.d.ts which is a super helpful file that contains references to all other tsd files so you only have to reference a single tsd in your TypeScript files to get Intellisense for all libraries.

Now install some grunt task packages. Run the following commands:

$npm install grunt-ts --save-dev

(installs grunt-ts package, will use the typescript tsc compiler to transpile your ts files to js files and generate maps)

$npm install grunt-tsd@next --save-dev

(installs grunt-tsd package, will keep your typescript definitions up to date)

$npm install grunt-karma --save-dev

(installs grunt-karma package, will be used to run unit tests with karma from grunt)

Let’s make sure that everything is still working nicely, run...

$grunt build

This will run all of the grunt build tasks. If you have any errors, address them before moving on.

Time to create some TypeScript files

The basics are in place, so create a new typescript file. Let’s replace app.js with typescript. For best practice, let’s split up core dependencies, app dependencies and app config into three different file.

Open Visual Studio Code

Now go to File - Open… and open the project directory you created in previous steps.
Create a new file in Visual Studio Code in /app and call it app.core.ts

Now let’s split out angular app module definition and angular dependency injection into app.core.ts.
First off, add a reference at the top of the file to tsd.d.ts so we get intellisense for angular and jquery.

Then delcare an IIFE (closure) using TypeScript. Explicitly set the return type to void for best type practice.

Now add the angular module instantiation and all of the angular dependencies from app.js.

Create another new TypeScript file called app.module.ts. This file will contain our app instantiation and add our core module as a dependency, so we end up with a clean module file and still get all of the core angular dependencies injected.

And finally create app.config.ts and put all of the app config code in there.

Grunt TypeScript Task Setup

Beauty. Now we setup our grunt TypeScript tasks to cleanup definitions if need be and transpile our ts into js. We need to edit our Gruntfile.js to include config, execution and definition of grunt-ts and grunt-tsd.

Open Gruntfile.js in Visual Studio Code

Add a ts watch task to grunt.initConfig : watch {}

Then add ts and tsd task configs to grunt.initConfig

And then tell grunt to load both npm tasks...

Add grunt-ts to

Add both ts and tsd to the grunt build tasks

Now run...

$grunt ts

This will create .js and .map files in your app/scripts directory for the .ts files we created.

And finally

Now we just need to update index.html with references to our new angular js files. Update script references at the bottom of index.html to the following:

and then run...

$grunt serve

The site should launch in your browser again and everything should still work.

Going forward

When you start development activities, just run...

$grunt serve

Grunt will monitor for file changes as you develop and transpile your TypeScript files into js as you save them.


Alguém said...

I spent a lot of time to figure out the problem when I tried to install grunt-kama coping your code $npm install grunt-karma —-save-dev.
The problem is on the (—-save-dev) should be -—save-dev.
Will be good if you update this for future followers

Alguém said...

also good to put on code tags ;)

Aaron Schnieder said...

Thanks for the feedback. Updated formatting for easy copy/paste of the commands and added code blocks.