hckr.fyi // thoughts

Setting Up Your Development Environment to Build Bots

by Michael Szul on

As many of you know, I've been on a Bot Framework kick over the last several months. We did a podcast episode several months back exclusively talking about the technology (I built a sample bot leading up to the episode), and shortly after I had a proposal accepted at the edUi Conference to speak about building bots. Recently, I've been working on a series of video tutorials about building bots in the Microsoft Bot Framework with NodeJS and TypeScript. I have a ton of information floating around in my head, and it's been an interesting process to try to find the right medium to use to get it out. I've been contemplating using GitBook, writing a series of blog posts, or even just getting it out as one single book. We'll see how things play out, but in the meantime, I'm going to dump a few tidbits of information on the codepunk blog for those interested. In this particular post, I'm going to talk about one of the ways to setup your development environment for building bots.

Before you get started building a bot, you will need to set up a development environment. TypeScript can be installed either through an installer that is essentially a Visual Studio extension installer, or through NodeJS’s package manager (NPM). If you want to use Visual Studio, go to the TypeScript web site and download the appropriate Visual Studio package. This package will install a version of TypeScript, the MSBuild tasks for use in building projects from either Visual Studio or the MSBuild command line utility, and Visual Studio GUI extensions for the project properties. One important thing to note is that these packages--although regularly updated--are not updated as much as the TypeScript NodeJS module.

For our purposes here, we will install TypeScript using NPM. This means that you will need to have NodeJS installed on your computer. You can download it from the NodeJS web site. TypeScript can be install globally for use across your file system:

npm install typescript -g
    

…but my recommendation is to actually install this locally within your project. This way, when you deploy your bot, you will have greater control over the TypeScript version in the event that the environment you are deploying to has an outdated or incompatible version.

Since we are going to install TypeScript locally, let us first set up our package.json file. From the command line, navigate to a folder where you will keep your project. I program on a Windows machine, and I like to keep all of my projects in a folder named x. Yes, just the letter "x"--a convention that dates back to when I built applications for a company using just XML and XSLT. From the root of the C-drive (or if you're on Linux, you can just put this in your home folder using the appropriate commands):

mkdir x
    cd x
    mkdir consolebot
    cd consolebot
    npm init
    

NPM will then ask you a series of questions about your project. You can fill this in, or you can just accept the defaults. Make sure that you set the entry point of your application to ./dist/app.js. We will go over why later. Once your package.json file is created, you can add the package dependencies, including TypeScript:

npm install typescript --save
    npm install botbuilder --save
    

The --save will write the dependencies to the package.json file so that when the bot is deployed to a server, the deployment script will know which packages to install.

Now that your folder structure and environment is set up, we have to decide on a text editor or IDE. You could use Visual Studio like I mentioned above, but I like to use Visual Studio Code, which is Microsoft's cross-platform, lightweight editor. Really, it is a lightweight IDE that uses a command palette and extensions to keep the application speed up, and the bulkiness down.

Visual Studio Code (VSCode) is written on top of the Electron shell, which is a JavaScript UI tooling component based on Chromium, and originally extracted from the Atom Editor (build by the team at GitHub). VSCode shares a lot of similarities with the Atom Editor, and all of the examples in this book can be written in your choice of text editor, whether VSCode, Atom, Brackets, Sublime, Textmate, or Visual Studio proper. We are going to take advantage of a few VSCode features for building and debugging, but all of this can be done in other editor flavors as well.

You can down VSCode from the Visual Studio web site. If you have Chocolatey installed as a Windows package manager, you can use:

cinst visualstudiocode
    

Once installed, VSCode has a command line interface that allows you to open files and folders from the command line. For example, if you had VSCode installed after setting up your package.json file, you can run this command from the command line:

code ./
    

…and it would open up the current folder as a folder in VSCode.

Now you have your editor, your package.json file, and you have your packages installed. Let us set up one more thing before you build your first bot. TypeScript allows you to put all of your configuration into a tsconfig.json file, so that you don't clutter your command line with command line switches. If you haven't already run the code command above, do so. Then create a tsconfig.json file in the root of your project folder. Here is an example:

{
        "compilerOptions": {
                    "module": "commonjs", 
                    "target": "es6",
                    "outDir": "./dist",
                    "sourceMap": true,
                    "declaration": false,
                    "removeComments": true
                },
        "files": [
              "./src/app.ts"
        ],
        "exclude": [
            "./node_modules",
            "./dist"
        ]
    }
    

What does all this mean? For one, we set the compilerOptions to direct the output of the TypeScript compilation. We are targeting the CommonJS module loading system, and the ES6 JavaScript standard. The output directory is going to be the dist folder. We want a source map for debugging purposes, but we don't want a declaration file to be created. We also want to remove any TypeScript comments from the generated output file. The files array, meanwhile, is a list of files we want to compile when we run the build. Right now we have just one file: app.ts. Remember from earlier that we set the entry point for the package.json file to ./dist/app.js. This is the generated code output of our ./src/app.ts file. Lastly, we exclude a few directories from the TypeScript compilation.

From the command line, you can run:

tsc -p ./tsconfig.json
    

From VSCode, you can just hit Ctrl + Shift + B, and choose the TypeScript build you want.