John Lancaster
100 lines
3.1 KiB
Markdown
100 lines
3.1 KiB
Markdown
# Configure Project Tasks in tasks.json
|
|
|
|
Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging.
|
|
|
|
## Minimal File
|
|
|
|
```json
|
|
{
|
|
"version": "2.0.0",
|
|
"tasks": []
|
|
}
|
|
```
|
|
|
|
## Task Fields You Will Use Most
|
|
|
|
- `label`: Task name shown in VS Code.
|
|
- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).
|
|
- `command`: Executable to run.
|
|
- `args`: Command arguments.
|
|
- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
|
|
- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)).
|
|
- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)).
|
|
- `isBackground`: `true` for long-running tasks (for example dev server watch).
|
|
|
|
## Python Project Example
|
|
|
|
```json
|
|
{
|
|
"version": "2.0.0",
|
|
"tasks": [
|
|
{
|
|
"label": "App: Run",
|
|
"type": "shell",
|
|
"command": "uv",
|
|
"args": ["run", "uvicorn", "personal_mcp.main:app", "--host", "127.0.0.1", "--port", "8000", "--reload"],
|
|
"options": {
|
|
"cwd": "${workspaceFolder}"
|
|
},
|
|
"isBackground": true,
|
|
"problemMatcher": []
|
|
},
|
|
{
|
|
"label": "Tests: Pytest",
|
|
"type": "shell",
|
|
"command": "uv",
|
|
"args": ["run", "pytest"],
|
|
"options": {
|
|
"cwd": "${workspaceFolder}"
|
|
},
|
|
"group": "test",
|
|
"problemMatcher": []
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Connect Tasks to Debug Profiles
|
|
|
|
In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes):
|
|
|
|
```json
|
|
{
|
|
"name": "FastAPI: Attach",
|
|
"type": "debugpy",
|
|
"request": "attach",
|
|
"connect": {
|
|
"host": "127.0.0.1",
|
|
"port": 5678
|
|
},
|
|
"preLaunchTask": "App: Run"
|
|
}
|
|
```
|
|
|
|
Use this only when startup sequencing is needed.
|
|
|
|
## Task Design Guidelines
|
|
|
|
1. Keep labels stable and descriptive.
|
|
2. Prefer one task per intent instead of monolithic shell commands.
|
|
3. Keep shell portability in mind if teammates use multiple OSes.
|
|
4. Avoid embedding secrets directly in task definitions.
|
|
5. Mark long-running tasks with `isBackground` and keep matchers explicit.
|
|
|
|
## Troubleshooting
|
|
|
|
If a task fails unexpectedly:
|
|
|
|
1. Run the underlying command directly in terminal.
|
|
2. Confirm `options.cwd` points to expected workspace root.
|
|
3. Confirm tool availability in environment path.
|
|
4. Confirm quoting and argument boundaries in `args`.
|
|
5. Confirm the task is not blocked by an outdated background process.
|
|
|
|
## Source Documentation
|
|
|
|
- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks)
|
|
- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix)
|
|
- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference)
|
|
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|