Temporal for VS Code
Tags: temporal, workflows, debugging
Published: 2023-05-25 19:53:02

---
title: Temporal for VS Code
published: true
description: Easily debug past or running workflows with Temporal's extension for Visual Studio Code
tags: temporal, workflows, debugging
cover_image: https://assets.temporal.io/w/vscode-social.png
---

We just published the first version of our [extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=temporal-technologies.temporalio). It currently improves the debugging experience for TypeScript workflows, and in the future we'd like to add other languages, features, and editors. If you have ideas, open an issue in the [GitHub repo](https://github.com/temporalio/vscode-debugger-extension)!

![Temporal for VS Code banner](//images.ctfassets.net/0uuz8ydxyd9p/3ta47lMdxjiUMfU7BjuNOu/18233120dee0bcd59f81376106f46509/vscode.png)

When you run a workflow function, each step it takes is stored as an event in a list called the Event History. You can download a workflow's Event History from the UI or CLI in a JSON file and have an SDK [replay it](https://docs.temporal.io/application-development/testing?lang=typescript#replay): the Worker calls your workflow function with the same arguments, the Worker immediately resolves activity calls with the return values recorded in Event History, and other things like timers going off and signals arriving happen in the same order they did previously. You can set breakpoints in workflow code to see what happened during the workflow's original execution. This ability to replay what happened during a function's execution, whether it's on a coworker's machine or in production, is a great help to debugging.

The Temporal VS Code extension improves the experience of replay debugging. It allows you to:

- Load Event Histories by Workflow Id or JSON file
- Easily start a replay
- Set breakpoints on events, not just code

## Usage

To learn how to use the extension, watch [this video](https://www.youtube.com/watch?v=3IjQde9HMNY) or follow these steps:

- Install [the extension](https://marketplace.visualstudio.com/items?itemName=temporal-technologies.temporalio)
- If you don’t already have a TypeScript workflow, create a project if you don't already have one:

  ```sh
  $ npx @temporalio/create@latest replay-demo --sample vscode-debugger
  $ code replay-demo
  ```

- If you do have a TypeScript workflow, add a file at `src/debug-replayer.ts` (or can [configure](#entrypoint) an alternate location):

  ```ts
  import { startDebugReplayer } from "@temporalio/worker"

  startDebugReplayer({
    workflowsPath: require.resolve("./workflows"),
  })
  ```

  And edit the `'./workflows'` path to match the location of your workflows file. This file is run the by the extension whenever you start a debug session. [`startDebugReplayer`](https://typescript.temporal.io/api/namespaces/worker#startdebugreplayer) creates a [replay Worker](https://docs.temporal.io/dev-guide/typescript/testing?lang=typescript#replay) (like [`Worker.runReplayHistory`](https://typescript.temporal.io/api/classes/worker.Worker#runreplayhistory) does) and communicates with the extension.

- Run `Temporal: Open Panel` (use `Cmd/Ctrl-Shift-P` to open Command Palette)

![Temporal: Open Panel](//images.ctfassets.net/0uuz8ydxyd9p/2G1v2wbMR053JyGmYx7yH6/7a9532b99a92f9ac5279f8c04af47136/open-panel.png)

- Enter a Workflow Id or choose a history JSON file (if you have the `replay-demo` project open, use [this file](assets.temporal.io/debugger-plugin-demo-event-history.json))

![MAIN tab of Temporal Panel](//images.ctfassets.net/0uuz8ydxyd9p/2t0PEQ5n2cWcqT6tfQZhEC/7f5e60bc50bf00256f6ec4c1d5dec996/choose-file.png)

- Click `Start`
- The Workflow Execution will start replaying and hit a breakpoint set on the first event:

![Debug session paused on the first line of the Workflow function](//images.ctfassets.net/0uuz8ydxyd9p/3KXvrYFx4Uspi1aBGb9OBc/e01e77633d1f9f5efe62267f04268c0c/started.png)

- Set breakpoints in code or on history events. Here's a breakpoint on the `sleep` line as well as the history event when the verify Signal arrives:

![Red breakpoint dots on a line of code and an event in the HISTORY tab of the Temporal Panel](//images.ctfassets.net/0uuz8ydxyd9p/71Tu0Kd3AQlIPUrHaoaKNK/59fbc2b9d4c1088111bda55145864a54/set-breakpoints.png)

- Hit play or step forward. In this example, after you hit play, it goes until the `WorkflowExecutionSignaled` event, pausing on the first line of the Signal handler:

![Paused on first line of the Signal handler](//images.ctfassets.net/0uuz8ydxyd9p/c8BL8aKfFaKhhXZ4qjWzJ/56bf202a9605d74032a11a1b14767d02/first-play.png)

  When you hit play again, it stops on the `sleep` line:

  ![Paused on sleep('1 day')](//images.ctfassets.net/0uuz8ydxyd9p/75q5t3IXKBVPmG9WZ9aijg/03c9f23b8549d803ace2a71f9f0c4d57/second-play.png)

  You can see on the top left that the `verified` variable is now `true`.

- To restart from the beginning, click the green restart icon:

![Top bar of debugging icons](//images.ctfassets.net/0uuz8ydxyd9p/14i9m2jSJun0yjnbLGTufe/34b68d8f70d57f8eceff3154bc7cb74b/restart.png)

  If instead of restarting, you step forward or hit play again, the debugging session will end (the replay Worker gets to the end of this history file and exits). Once a debug session has ended, to restart it, go back to the `MAIN` tab and `Start` again.

The `humanVerificationWorkflow` workflow used above is in [`temporalio/samples-typescript`](https://github.com/temporalio/samples-typescript/blob/main/vscode-debugger/src/workflows.ts). For a more in-depth demo, see [this video](https://www.youtube.com/watch?v=3IjQde9HMNY).

## Configuration

### Server

When starting a replay by Workflow Id (and optionally Run Id), the extension downloads the history from the Temporal Server. By default, it connects to a Server running on the default `localhost:7233`.

To connect to a different Server:

- Open the `SETTINGS` tab
- Edit the `Address` field
- If you're using TLS (e.g. to connect to Temporal Cloud), check the box and select your client cert and key

![SETTINGS tab of Temporal Panel](//images.ctfassets.net/0uuz8ydxyd9p/YEkTnasEpExyFnRa4tsUz/552b20eee7e29ed3a120856f6e99751f/settings.png)

### Entrypoint

By default, the extension will look for the file that calls [`startDebugReplayer`](https://typescript.temporal.io/api/namespaces/worker#startdebugreplayer) at `src/debug-replayer.ts`. To use a different TypeScript or JavaScript file, set the `temporal.replayerEntrypoint` config:

- Open or create `.vscode/settings.json`
- Add the config field:

  ```json
  {
    "temporal.replayerEntrypoint": "test/different-file.ts"
  }
  ```

---

That's the extension! If you have any problems with it, please [open an issue](https://github.com/temporalio/vscode-debugger-extension/issues). We also welcome contributions—please get consensus for your plan in an issue before submitting a PR ☺️. Happy debugging! 🐞💃