BrightScript Tasks

The BrightScript language extension provides a task system that integrates with VS Code's task runner, allowing you to automate common development workflows like building, testing, and linting.

• Custom shell commands with variable substitution
• Interactive folder selection with glob patterns
• Environment variables and custom working directories
• Problem matcher integration for error detection
• Background task support for watchers

Tasks are defined in .vscode/tasks.json in your workspace. Here's a simple example:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "brightscript",
            "label": "Build Project",
            "command": "npx bsc"
        }
    ]
}

• type: Must be "brightscript" to use the BrightScript task provider
• label: Display name shown in the task picker
• command: The shell command to execute

BrightScript tasks support variable substitution in the command field. Variables are resolved before the command is executed.

The ${folderForFile: <glob>} variable finds files matching a glob pattern and resolves to the directory containing those files. This is useful in monorepos or multi-project workspaces.

Example: Build a specific project

{
    "type": "brightscript",
    "label": "Build Selected Project",
    "command": "cd ${folderForFile: **/bsconfig.json} && npx bsc"
}

When you run this task:

• If one bsconfig.json is found, it uses that directory automatically
• If multiple are found, you get a quick pick menu to select which project

Common glob patterns:

Note: Files in node_modules are automatically excluded.

Add environment variables available to your command:

{
    "type": "brightscript",
    "label": "Build with Custom Env",
    "command": "npx bsc",
    "options": {
        "env": {
            "NODE_ENV": "production"
        }
    }
}

{
    "type": "brightscript",
    "label": "Build from Subdirectory",
    "command": "npx bsc",
    "options": {
        "cwd": "${workspaceFolder}/apps/my-roku-app"
    }
}

Problem matchers parse command output to detect errors and warnings. Here's a basic example for BrighterScript compiler output:

{
    "type": "brightscript",
    "label": "Compile",
    "command": "npx bsc",
    "problemMatcher": {
        "owner": "brightscript",
        "fileLocation": "relative",
        "pattern": {
            "regexp": "^(.*)\\((\\d+),(\\d+)\\):\\s+(error|warning)\\s+(.*)$",
            "file": 1,
            "line": 2,
            "column": 3,
            "severity": 4,
            "message": 5
        }
    }
}

Background tasks are useful for file watchers or development servers:

{
    "type": "brightscript",
    "label": "Watch",
    "command": "npx bsc --watch",
    "isBackground": true
}

Use tasks as pre-launch actions to build your project before debugging:

{
    "type": "brightscript",
    "name": "Launch on Roku",
    "request": "launch",
    "host": "${promptForHost}",
    "password": "${promptForPassword}",
    "preLaunchTask": "Build Project"
}

Here's a basic tasks.json for a monorepo workflow:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "brightscript",
            "label": "Build Selected Project",
            "command": "cd ${folderForFile: **/bsconfig.json} && npx bsc",
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "type": "brightscript",
            "label": "Watch Selected Project",
            "command": "cd ${folderForFile: **/bsconfig.json} && npx bsc --watch",
            "isBackground": true
        }
    ]
}

Task not found:

• Ensure type is set to "brightscript"
• Verify tasks.json has valid JSON syntax

Variable not resolving:

• Check that files matching the glob pattern exist
• Remember that node_modules is excluded

Command not executing:

• Check the terminal output for errors
• Verify the command works in a regular terminal
• Ensure required programs are in your PATH

• Use descriptive task labels
• Add problem matchers for instant error feedback
• Set default build and test tasks for keyboard shortcuts
• Use the ${folderForFile} variable for monorepo flexibility

• VS Code Tasks Documentation
• Variable Substitutions