These tools are mostly run from the command line and automate jobs inside and outside the inner software development loop (edit, compile, test, and debug). Given their importance in the development life-cycle, it is very helpful to be able to run tools and analyze their results from within VS Code.

Note: Task support is only available when working on a workspace folder. It is not available when editing single files.

TypeScript Hello World

Let's start with a simple "Hello World" TypeScript program that we want to compile to JavaScript.

Create an empty folder "mytask", generate a tsconfig.json file and start VS Code from that folder.

Pressing ⇧⌘B (Windows, Linux Ctrl+Shift+B) or running Run Build Task... from the global Tasks menu show the following picker:

Selecting the entry executes the TypeScript compiler and translates the TypeScript file to a JavaScript file. When the compiler has finished, there should be a HelloWorld.js file.

You can also define the TypeScript build task as the default build task so that it is executed directly when triggering Run Build Task (⇧⌘B (Windows, Linux Ctrl+Shift+B)). To do so, select Configure Default Build Task from the global Tasks menu. This shows you a picker with the available build tasks. Select TypeScript and VS Code will generate the following tasks.json file:

Unlike the previous 0.1.0 version of the tasks.json file, this does not define a new task. It annotates the TypeScript compile tasks contributed by VS Code's TypeScript extension to be the default build task. You can now execute the TypeScript compiler by simply pressing ⇧⌘B (Windows, Linux Ctrl+Shift+B).

Task auto-detection

VS Code currently auto-detects tasks for the following systems: Gulp, Grunt, Jake and npm. We are working with the corresponding extension authors to add support for Maven and the C# dotnet command as well. If you develop a JavaScript application using Node.js as the runtime, you usually have a package.json file describing your dependencies and the scripts to run. If you have cloned the eslint-starter example, then executing Run Tasks from the global menu shows the following list:

Select npm: install to install the necessary Node.js modules. When prompted to select a problem matcher, select Continue without scanning the build output. This will install all necessary Node.js modules.

Now open the server.js file and add a semicolon to the end of a statement (note the ESLint starter assumes statements without a semicolon) and execute the Run Tasks again. This time select the npm: run lint task. When prompted for the problem matcher to use, select ESLint stylish

Executing the task produces one error shown in the Problems view:

In addition, VS Code created a tasks.json file with the following content:

Custom tasks

Not all tasks or scripts can be auto-detected in your workspace. Sometimes it is necessary to define your own custom tasks. Assume you have a script to run your tests since it is necessary to setup some environment correctly. The script is stored in a script folder inside your workspace and named test.sh for Linux and macOS and test.cmd for Windows. Run Configure Tasks from the global Tasks menu. This opens the following picker:

Note: If you don't see the list of task runner templates, you may already have a tasks.json file in your folder and its contents will be open in the editor. Close the file and either delete or rename it for this example.

We are working on more auto-detection support, so this list will get smaller and smaller in the future. Since we want to write our own custom task, select Others from the list. This opens the tasks.json file with a task skeleton. Replace the contents with the following:

type: The task's type. For a custom task, this can either be shell or process. If shell is specified, the command is interpreted as a shell command (for example: bash, cmd, or PowerShell). If process is specified, the command is interpreted as a process to execute. If shell is used, any arguments to the command should be embedded into the command property to support proper argument quoting. For example, if the test script accepts a --debug argument then the command property would be: ./scripts/test.sh --debug.

command: The actual command to execute.

windows: Any Windows specific properties. Will be used instead of the default properties when the command is executed on the Windows operating system.

group: Defines to which group the task belongs. In the example, it belongs to the test group. Tasks that belong to the test group can be executed by running Run Test Task from the Command Palette.

presentation: Defines how the task output is handled in the user interface. In this example, the Integrated Terminal showing the output is always revealed and a new terminal is created on every task run.

There are more task properties to configure your workflow. You can use IntelliSense with ⌃Space (Windows, Linux Ctrl+Space) to get an overview of the valid properties.

In addition to the global menu bar, task commands can be accessed using the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). You can filter on 'task' and can see the various task related commands.

Output behavior

Sometimes you want to control how the Integrated Terminal panel behaves when running tasks. For instance, you may want to maximize editor space and only look at task output if you think there is a problem. The behavior of the terminal can be controlled using the presentation property of a task. It offers the following properties:

shared: The terminal is shared and the output of other task runs are added to the same terminal.

dedicated: The terminal is dedicated to a specific task. If that task is executed again, the terminal is reused. However the output of a different task is presented in a different terminal.

new: Every execution of that task is using a new clean terminal.

You can modify the terminal panel behavior for auto-detected tasks as well. For example, if you want to change the output behavior for the npm: run lint from the ESLint example from above, simply add the presentation property to it:

Customizing auto-detected tasks

As mentioned above, you can customize auto-detected tasks in the tasks.json file. You usually do so to modify presentation properties or to attach a problem matcher to scan the task's output for errors and warnings. You can customize a task directly from the Run Task list by pressing the gear icon to the right to insert the corresponding task reference into the tasks.json file. Assume you have the following Gulp file to lint JavaScript files using ESLint (the file is taken from https://github.com/adametry/gulp-eslint):

const gulp = require('gulp');
const eslint = require('gulp-eslint');
gulp.task('lint', () => {
// ESLint ignores files with "node_modules" paths.// So, it's best to have gulp ignore the directory as well.// Also, Be sure to return the stream from the task;// Otherwise, the task may end before the stream has finished.return gulp.src(['**/*.js','!node_modules/**'])
// eslint() attaches the lint output to the "eslint" property// of the file object so it can be used by other modules.
.pipe(eslint())
// eslint.format() outputs the lint results to the console.// Alternatively use eslint.formatEach() (see Docs).
.pipe(eslint.format())
// To have the process exit with an error code (1) on// lint error, return the stream and pipe to failAfterError last.
.pipe(eslint.failAfterError());
});
gulp.task('default', ['lint'], function () {
// This will only run if the lint task is successful...
});

Executing Run Task from the global Tasks menu will show the following picker:

Variable substitution

When authoring tasks configurations, it is useful to have a set of predefined common variables such as the active file (${file}) or workspace root folder (${workspaceFolder}). VS Code supports variable substitution inside strings in the tasks.json file and you can see a full list of predefined variables in the Variables Reference.

Below is an example of a custom task configuration that passes the current opened file to the TypeScript compiler.

Operating system specific properties

The task system supports defining values (for example, the command to be executed) specific to an operating system. To do so, put an operating system specific literal into the tasks.json file and specify the corresponding properties inside that literal.

Below is an example that uses the Node.js executable as a command and is treated differently on Windows and Linux:

Valid operating properties are windows for Windows, linux for Linux, and osx for macOS. Properties defined in an operating system specific scope override properties defined in the task or global scope.

Task properties can also be defined in the global scope. If present, they will be used for specific tasks unless they define the same property with a different value. In the example below, there is a global presentation property that defines that all tasks should be executed in a new panel:

Changing the encoding for a task output

Task frequently act with files on disk. If these files are store on disk with an encoding different than the system encoding you need to let the command executed as a task know which encoding to use. Since this depends on the operating system and the shell used there is no general solution to control this. Below some advice and examples on how to make it work.

If you need to tweak the encoding you should check whether it makes sense to change the default encoding used by our operating system or at least changing it for the shell you use by tweaking the shell's profile file.

If you only need to tweak it for a specific task then add the OS specific command necessary to change the encoding to the tasks command line. The following example is for Windows using code page of 437 as its default. The task shows the output of a file containing Cyrillic characters and therefore needs code page 866. The task to list the file looks like this assuming that the default shell is set to cmd.exe:

If the task is execute in PowerShell the command needs to read like this chcp 866; more russian.txt. Under Linux and Mac the locale command can be used to inspect the locale and tweak the necessary environment variables.

Examples of tasks in action

To highlight the power of tasks, here are a few examples of how VS Code can use tasks to integrate external tools like linters and compilers.

Transpiling TypeScript to JavaScript

The TypeScript topic includes an example that creates a task to transpile TypeScript to JavaScript and observe any related errors from within VS Code.

Compiling Markdown to HTML

The Markdown topic provides two examples for compiling Markdown to HTML:

Transpiling Less and Sass into CSS

Defining a problem matcher

VS Code ships some of the most common problem matchers 'in-the-box'. However, there are lots of compilers and linting tools out there, all of which produce their own style of errors and warnings so you may want to create your own problem matcher.

We have a helloWorld.c program in which the developer mistyped printf as prinft. Compiling it with gcc will produce the following warning:

helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’

We want to produce a problem matcher that can capture the message in the output and show a corresponding problem in VS Code. Problem matchers heavily rely on regular expressions. The section below assumes you are familiar with regular expressions.

Tip: We have found the RegEx101 playground to be a great way to develop and test regular expressions.

A matcher that captures the above warning (and errors) looks like this:

{
// The problem is owned by the cpp language service.
"owner": "cpp",
// The file name for reported problems is relative to the opened folder.
"fileLocation": ["relative", "${workspaceFolder}"],
// The actual pattern to match problems in the output.
"pattern": {
// The regular expression. Example to match: helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’ [-Wimplicit-function-declaration]
"regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
// The first match group matches the file name which is relative.
"file": 1,
// The second match group matches the line on which the problem occurred.
"line": 2,
// The third match group matches the column at which the problem occurred.
"column": 3,
// The fourth match group matches the problem's severity. Can be ignored. Then all problems are captured as errors.
"severity": 4,
// The fifth match group matches the message.
"message": 5}
}

Please note that the file, line and message properties are mandatory.

Here is a finished tasks.json file with the code above (comments removed) wrapped with the actual task details:

Our problem matcher is line-based so we need to capture the file name (test.js) with a different regular expression than the actual problem location and message (1:0 error Missing "use strict" statement).

To do this we use an array of problem patterns for the pattern property. This way you define a pattern per each line you want to match.

The following problem pattern matches the output from ESLint in stylish mode - but still has one small issue which we will resolve next. The code below has a first regular expression to capture the file name and the second to capture the line, column, severity, message and error code:

The pattern's first regular expression will match "test.js", the second "1:0 error ...". The next line "1:9 error ..." is processed but not matched by the first regular expression and so no problem is captured.

To make this work, the last regular expression of a multi-line pattern can specify the loop property. If set to true, it instructs the task system to apply the last pattern of a multi-line matcher to the lines in the output as long as the regular expression matches.

The information captured by all previous patterns is combined with the information captured by the last pattern and turned into a problem inside VS Code.

Background / watching tasks

Some tools support running in the background while watching the file system for changes and then triggering an action when a file changes on disk. With Gulp such functionality is provided through the npm module gulp-watch. The TypeScript compiler tsc has built in support for this via the --watch command line option.

To provide feedback that a background task is active in VS Code and producing problem results, a problem matcher has to use additional information to detect these state changes in the output. Let's take the tsc compiler as an example. When the compiler is started in watch mode, it prints the following additional information to the console:

Convert from "0.1.0" to "2.0.0"

Note: If you have created a workspace that consists of multiple folders (Multi-root Workspace), only version 2.0.0 tasks are detected and shown in the Tasks > Run Task... picker.

Try running without tasks.json

Tasks 2.0.0 version comes with lots of new auto-detection features so you can try removing an existing tasks.json file to see which tasks still work. Simply rename the existing tasks.json to tasks.json.off.

Migrating to Tasks 2.0.0

If you have lots of task customizations then you can switch by changing the version attribute to "2.0.0". After doing so, you might encounter warnings (green squigglies) because some properties are now deprecated.

suppressTaskName: By default, the task name gets appended to the list of arguments when running a task version 0.1.0. Since version 2.0.0 supports commands per task, simply inline the command into the task and specify the arguments accordingly.