← Back to DevBytes
Web August 14, 2026 10 min read

WebStorm Task Running: Complete Guide

WebStorm Task Running: Complete Guide

WebStorm, JetBrains' flagship JavaScript IDE, ships with powerful built-in support for task runners. Instead of constantly switching between your editor and terminal to run build scripts, linters, test suites, or bundlers, you can configure, trigger, and monitor these tasks directly inside the IDE. This guide walks through everything you need to know to make task running in WebStorm a seamless part of your workflow.

What Is Task Running in WebStorm?

Task running in WebStorm refers to the IDE's ability to integrate with popular JavaScript task runners and build tools — such as npm scripts, Gulp, Grunt, and even custom shell commands — and execute them from within the editor. WebStorm detects your project's task configuration files, parses available tasks, and exposes them through a dedicated UI. Output from these tasks is streamed into the IDE's Run tool window, where you can inspect logs, click stack traces, and jump straight to failing lines of code.

At its core, task running in WebStorm is powered by the concept of Run Configurations — reusable definitions that describe what to run, with what arguments, in which environment, and with what pre- and post-task steps. These configurations can be shared with your team, saved to version control, and triggered with keyboard shortcuts.

Why Task Running Matters

Integrating task runners into your IDE offers several concrete benefits:

Supported Task Runners

WebStorm provides first-class integration with several task runners out of the box:

Getting Started with npm Scripts

The most common task runner in modern JavaScript projects is npm itself, via the scripts field in package.json. WebStorm automatically detects these scripts and makes them available in the npm tool window.

A Sample package.json

Consider a typical project with the following package.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src --ext .js,.ts,.jsx,.tsx",
    "test": "vitest run",
    "test:watch": "vitest",
    "format": "prettier --write ."
  },
  "devDependencies": {
    "eslint": "^8.57.0",
    "prettier": "^3.2.5",
    "vite": "^5.2.0",
    "vitest": "^1.6.0"
  }
}

Viewing and Running npm Scripts

Once WebStorm indexes your project, open the npm tool window by navigating to View → Tool Windows → npm in the menu bar, or by clicking the npm icon on the left tool window bar. You will see a tree of all scripts defined in package.json. From here you can:

Alternatively, you can open the package.json file in the editor. WebStorm displays a small green play icon in the gutter next to each script. Click it to run the script or to create a run configuration.

Creating an npm Run Configuration Manually

To create an npm run configuration from scratch, follow these steps:

You can now run this configuration from the toolbar dropdown, the Run menu, or a keyboard shortcut (the default is Shift + F10 on Windows/Linux and Ctrl + R on macOS).

Working with Gulp Tasks

If your project uses Gulp, WebStorm parses your gulpfile.js and lists every defined task in the Gulp tool window. This is especially useful for projects with complex build pipelines.

A Sample gulpfile.js

const { src, dest, series, parallel } = require('gulp');
const sass = require('gulp-sass')(require('sass'));
const cleanCSS = require('gulp-clean-css');
const rename = require('gulp-rename');

function compileSass() {
  return src('src/scss/**/*.scss')
    .pipe(sass().on('error', sass.logError))
    .pipe(dest('dist/css'));
}

function minifyCss() {
  return src('dist/css/**/*.css')
    .pipe(cleanCSS())
    .pipe(rename({ suffix: '.min' }))
    .pipe(dest('dist/css'));
}

function copyAssets() {
  return src('src/assets/**/*')
    .pipe(dest('dist/assets'));
}

const build = series(compileSass, minifyCss, copyAssets);

exports.compileSass = compileSass;
exports.minifyCss = minifyCss;
exports.copyAssets = copyAssets;
exports.build = build;
exports.default = build;

Running Gulp Tasks in WebStorm

Open the Gulp tool window via View → Tool Windows → Gulp. WebStorm displays a tree of all exported tasks. You can double-click any task to run it, or right-click to create a persistent run configuration.

To create a Gulp run configuration manually:

Working with Grunt Tasks

Grunt integration works similarly to Gulp. WebStorm parses your Gruntfile.js and lists registered tasks in the Grunt tool window.

A Sample Gruntfile.js

module.exports = function (grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),

    concat: {
      options: {
        separator: '\n',
      },
      dist: {
        src: ['src/js/**/*.js'],
        dest: 'dist/built.js',
      },
    },

    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n',
      },
      build: {
        src: 'dist/built.js',
        dest: 'dist/built.min.js',
      },
    },
  });

  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-contrib-uglify');

  grunt.registerTask('default', ['concat', 'uglify']);
  grunt.registerTask('build', ['concat', 'uglify']);
};

Open the Grunt tool window via View → Tool Windows → Grunt to see and run available tasks. You can also create a Grunt run configuration from Edit Configurations by selecting Grunt.js and specifying the Gruntfile and task name.

Chaining Tasks with Before Launch Options

One of WebStorm's most powerful features is the ability to chain tasks using the Before launch section of a run configuration. This lets you run other configurations, external tools, file watchers, or even arbitrary scripts before the main task starts.

Example: Lint Before Running Tests

Suppose you want to run your linter every time you run the test suite. You can configure this as follows:

Now, whenever you run the Test configuration, WebStorm will automatically run the linter first. If the linter fails, the test run will not proceed.

Example: Start a Dev Server with a File Watcher

You can also use Before launch to compile TypeScript before starting a dev server:

// Before launch configuration for a "Dev Server" run config:
// 1. Run npm script "build:ts" (compiles TypeScript)
// 2. Run external tool "Start Watcher" (tsc --watch)
// 3. Main task: npm run dev (starts Vite dev server)

Running Tasks with Environment Variables

Many tasks require environment variables — API keys, feature flags, or Node options. WebStorm lets you define these per run configuration. For example, to run a build with a specific API endpoint:

These variables are scoped to the run configuration and will not leak into your global shell environment.

Using the Run Tool Window

When a task runs, its output appears in the Run tool window at the bottom of the IDE. Key features include:

Assigning Keyboard Shortcuts

To maximize productivity, assign keyboard shortcuts to your most-used run configurations. Here's how:

For example, you might map Ctrl + Shift + D to your dev server configuration and Ctrl + Shift + T to your test configuration.

Sharing Run Configurations with Your Team

Run configurations can be stored in two ways: locally (in .idea/workspace.xml, which is typically gitignored) or as shared files (in the .idea/runConfigurations/ directory, which can be committed). To share a configuration:

The resulting file looks something like this:

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Build" type="js.build_tools.npm">
    <package-json value="$PROJECT_DIR$/package.json" />
    <command value="run" />
    <scripts>
      <script value="build" />
    </scripts>
    <node-interpreter value="project" />
    <envs />
    <method v="2" />
  </configuration>
</component>

When a teammate pulls this file, the run configuration appears automatically in their IDE.

Best Practices

Prefer npm Scripts for Portability

While WebStorm's native Gulp and Grunt integrations are excellent, modern projects increasingly rely on npm scripts because they require no additional tooling and work identically in any editor or CI environment. Define your tasks in package.json and use WebStorm's npm integration to run them. This keeps your project portable for contributors who may not use WebStorm.

Use Compound Run Configurations for Multi-Step Workflows

If you frequently run multiple tasks together — for example, starting a dev server and a mock API server simultaneously — create a Compound run configuration:

Running the compound configuration launches all included tasks in parallel.

Keep the Output Window Clean

Long-running tasks like dev servers can produce enormous amounts of output. Use the Pin feature to preserve important output in a separate tab, and use the Restart button rather than creating duplicate run configurations. You can also configure WebStorm to clear the console before each run by enabling Run with Prior Console Clearance in the run configuration settings.

Leverage Before Launch for Reproducible Builds

Always chain a clean step before production builds to avoid stale artifacts. For example, configure your build run configuration to run rm -rf dist (via an external tool or npm script) as a Before launch step. This ensures every build starts from a clean state.

Use Environment Variable Files for Secrets

Avoid hardcoding secrets into run configurations. Instead, use a .env file and a tool like dotenv to load variables at runtime. If you must define environment variables in the run configuration, store the configuration locally (not as a shared project file) to avoid committing secrets to version control.

Debug Instead of Just Running

For tasks that execute JavaScript — such as test runners or custom Node scripts — use the Debug button instead of Run. This starts the task with the debugger attached, allowing you to set breakpoints, inspect variables, and step through code. To debug an npm script, create a run configuration for it and click the debug icon (green bug) instead of the run icon (green play).

Conclusion

WebStorm's task running capabilities transform the IDE from a mere code editor into a complete development environment. By configuring run configurations for your npm scripts, Gulp tasks, Grunt tasks, and custom commands, you can execute your entire build, test, and deployment pipeline without ever leaving the editor. Features like before-launch chaining, compound configurations, clickable error output, and shareable project files make it easy to build a workflow that is both fast for individuals and consistent across teams. Start by setting up run configurations for your most frequent tasks, assign keyboard shortcuts to them, and gradually incorporate before-launch steps and compound configurations as your project grows. The small upfront investment in configuration pays off every single day in reduced context switching and faster feedback loops.

— Ad —

Google AdSense will appear here after approval

← Back to all articles