Reactive VSCode

https://kermanx.com/reactive-vscode
Admin
Reactive VSCode is an extension API that enables developers to build VSCode extensions using a...
Tokens:14,772
Snippets:186
Trust Score:5.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example setup function implementation

Source: https://kermanx.com/reactive-vscode/guide/extension.html

Demonstrates registering commands, using configuration, logging, and reactive effects within the setup function.

```typescript
import { 
defineConfig
, 
defineExtension
, 
defineLogger
, 
useCommand
, 
useIsDarkTheme
, 
watchEffect
 } from 'reactive-vscode'
import { window } from 'vscode'
import { 
useDemoTreeView
 } from './treeView'

const 
config
 = 
defineConfig
<{
  
message
: string
}>('extension-id')

const 
logger
 = 
defineLogger
('Reactive VSCode')

export = 
defineExtension
(() => {
  
logger
.
info
('Extension Activated')
  
logger
.
show
()

  
useCommand
('reactive-vscode-demo.helloWorld', () => {
    window.
showInformationMessage
(
config
.
message
)
  })

  const 
isDark
 = 
useIsDarkTheme
()
  
watchEffect
(() => {
    
logger
.
info
('Is Dark Theme:', 
isDark
.
value
)
  })

  
useDemoTreeView
()
})
```

--------------------------------

### Run Development Mode

Source: https://kermanx.com/reactive-vscode/guide

Commands to start the development server for your extension.

```bash
pnpm dev
```

```bash
npm run dev
```

```bash
yarn dev
```

--------------------------------

### Install @reactive-vscode/vueuse

Source: https://kermanx.com/reactive-vscode/guide/vueuse.html

Commands to install the package using different package managers.

```bash
pnpm install -D @reactive-vscode/vueuse
```

```bash
npm install -D @reactive-vscode/vueuse
```

```bash
yarn add -D @reactive-vscode/vueuse
```

--------------------------------

### useAllExtensions

Source: https://kermanx.com/reactive-vscode/functions/useAllExtensions

A reactive hook that tracks the state of all installed extensions in VSCode.

```APIDOC
## useAllExtensions

### Description
Provides a reactive wrapper for the `extensions.all` property, allowing components to react to changes in the list of installed VSCode extensions.

### Signature
`useAllExtensions(): readonly Extension<any>[]`

### Returns
- **extensions** (readonly Extension<any>[]) - A reactive array containing all currently installed extensions.
```

--------------------------------

### Use VueUse functions in an extension

Source: https://kermanx.com/reactive-vscode/guide/vueuse.html

Example of importing and using a VueUse function within a reactive-vscode extension definition.

```ts
import { 
useIntervalFn
 } from '@reactive-vscode/vueuse'
import { 
defineExtension
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  
useIntervalFn
(() => {
    
console
.
log
('Hello World')
  }, 1000)
})
```

--------------------------------

### Register a folding range provider with useDisposable

Source: https://kermanx.com/reactive-vscode/guide/disposable.html

Automatically dispose of a folding range provider registration by wrapping it in useDisposable within the extension setup function.

```typescript
import type { TextDocument } from 'vscode'
import { 
defineExtension
, 
useDisposable
 } from 'reactive-vscode'
import { languages } from 'vscode'

export = 
defineExtension
(() => {
  
useDisposable
(languages.
registerFoldingRangeProvider
(
    { 
language
: 'markdown' },
    {
      
provideFoldingRanges
(
document
: TextDocument) {
        return []
      },
    },
  ))
})
```

--------------------------------

### Get and set document text with useDocumentText

Source: https://kermanx.com/reactive-vscode/guide/editor.html

Use useDocumentText to create a reactive binding to the text content of an active editor.

```ts
import type { ExtensionContext } from 'vscode'

import { 
computed
, 
defineExtension
, 
ref
, 
useActiveTextEditor
, 
useDocumentText
, 
watchEffect
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
editor
 = 
useActiveTextEditor
()
  const 
text
 = 
useDocumentText
(() => 
editor
.
value
?.
document
)

  // Reactive, may be set from other places
  const 
name
 = 
ref
('John Doe')

  
watchEffect
(() => {
    
text
.
value
 = `Hello, ${
name
.
value
}!`
  })
})
```

--------------------------------

### Create a New Project

Source: https://kermanx.com/reactive-vscode/guide

Commands to initialize a new Reactive VSCode project using different package managers.

```bash
pnpm create reactive-vscode
```

```bash
npm init reactive-vscode@latest
```

```bash
yarn create reactive-vscode
```

--------------------------------

### useQuickPick

Source: https://kermanx.com/reactive-vscode/functions/useQuickPick

Creates a customizable quick pick UI component using the underlying window.createQuickPick API.

```APIDOC
## useQuickPick

### Description
Creates a customizable quick pick UI component. This function acts as a reactive interface for the VSCode `window.createQuickPick` API.

### Usage
```typescript
const quickPick = useQuickPick();
```
```

--------------------------------

### useTerminal

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Creates a new terminal instance using the provided name and shell path, returning reactive controls for the terminal.

```APIDOC
## useTerminal(name: string, shellPath: string)

### Description
Creates a terminal via window.createTerminal. The parameters are the same as the standard VSCode window.createTerminal function.

### Returns
- **terminal**: The terminal instance
- **state**: Reactive state of the terminal
- **shellIntegration**: Shell integration status
- **sendText**: Function to send text to the terminal
- **show**: Function to show the terminal
- **hide**: Function to hide the terminal
```

--------------------------------

### Register a Webview View with useWebviewView

Source: https://kermanx.com/reactive-vscode/guide/view.html

Create an interactive webview panel that communicates with the extension via postMessage.

```ts
import { 
computed
, 
defineService
, 
ref
, 
useWebviewView
 } from 'reactive-vscode'

export const 
useDemoWebviewView
 = 
defineService
(() => {
  const 
message
 = 
ref
('')
  const 
html
 = 
computed
(() => `
  <script>
    vscode = acquireVsCodeApi()
    function updateMessage() {
      vscode.postMessage({
        type: 'updateMessage',
        message: document.querySelector('input').value,
      })
    }
  </script>
  <p>${
message
.
value
}</p>
  <div style="display:flex; flex-wrap:wrap;">
    <input type="text" placeholder="Input Message" />
    <button onclick="updateMessage()">Update Message</button>
  </div>
  `)

  const { 
postMessage
 } = 
useWebviewView
(
    'reactive-webview-view',
    
html
,
    {
      
webviewOptions
: {
        
enableScripts
: true,
        
enableCommandUris
: true,
      },
      
onDidReceiveMessage
(
ev
) {
        if (
ev
.type === 'updateMessage')
          
message
.
value
 = 
ev
.message
      },
    },
  )

  return { 
message
, 
postMessage
 }
})
```

--------------------------------

### useCommand

Source: https://kermanx.com/reactive-vscode/functions/useCommand

Registers a command in the VSCode environment using a reactive approach.

```APIDOC
## useCommand

### Description
Reactive API wrapper for `commands.registerCommand`. This function allows developers to register commands within the VSCode extension environment using a reactive pattern.

### Signature
`useCommand(command: string, callback: (...args: any[]) => any)`

### Parameters
- **command** (string) - The identifier of the command to register.
- **callback** (function) - The handler function to execute when the command is invoked.
```

--------------------------------

### Define View Containers and Views in package.json

Source: https://kermanx.com/reactive-vscode/guide/view.html

Configure the view container and individual views within the extension manifest.

```json
{
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "package-explorer",
          "title": "Package Explorer",
          "icon": "resources/package-explorer.svg"
        }
      ]
    },
    "views": {
      "package-explorer": [
        {
          "id": "package-dependencies",
          "name": "Dependencies"
        },
        {
          "id": "package-outline",
          "name": "Outline"
        }
      ]
    }
  }
}
```

--------------------------------

### Create a Terminal with useTerminal

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Initializes a new terminal instance using the specified name and shell path.

```typescript
import { 
defineExtension
, 
useTerminal
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const {
    
terminal
,
    
state
,
    
shellIntegration
,
    
sendText
,
    
show
,
    
hide
,
  } = 
useTerminal
('My Terminal', '/bin/bash')
})
```

--------------------------------

### useTextEditorCommand

Source: https://kermanx.com/reactive-vscode/functions/useTextEditorCommand

A reactive API wrapper for registering text editor commands in VSCode.

```APIDOC
## useTextEditorCommand

### Description
Provides a reactive interface for `commands.registerTextEditorCommand`. This allows developers to register commands that interact with the active text editor in a reactive manner.

### Usage
This function acts as a reactive wrapper for the standard VSCode `commands.registerTextEditorCommand` API.
```

--------------------------------

### Define Extension Entry Point

Source: https://kermanx.com/reactive-vscode/guide

Use the defineExtension function in your extension entry file to initialize the extension.

```ts
import { 
defineExtension
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  // Setup your extension here
})
```

--------------------------------

### Access and react to settings in TypeScript

Source: https://kermanx.com/reactive-vscode/guide/config.html

Use defineConfig to define configuration types and access settings, and watchEffect to react to configuration changes.

```ts
import { 
defineConfig
, 
watchEffect
 } from 'reactive-vscode'

const 
config
 = 
defineConfig
<{
  
enabled
: boolean
  
greeting
: {
    // Nested configurations are also supported
    
message
: string | null
  }
}>('your-extension-id')


console
.
log
(
config
.
greeting
.
message
) // read

config
.
greeting
.
message
 = 'Hi!' // write

config
.
greeting
 = { 
message
: 'Hello!' } // write nested object


watchEffect
(() => {
  
console
.
log
('Enabled:', 
config
.
enabled
) // react to changes
})
```

--------------------------------

### Define extension settings in package.json

Source: https://kermanx.com/reactive-vscode/guide/config.html

Add the contributes.configuration field to your package.json to register extension settings.

```json
{
  "contributes": {
    "configuration": {
      "title": "My Extension",
      "properties": {
        "myExtension.enable": {
          "type": "boolean",
          "default": true,
          "description": "Enable My Extension"
        },
        "myExtension.greeting.message": {
          "type": ["string", "null"],
          "default": "Hello!",
          "description": "Greeting messag. Set to null to disable"
        }
      }
    }
  }
}
```

--------------------------------

### Sync Theme to Webview

Source: https://kermanx.com/reactive-vscode/guide/window.html

Uses useActiveColorTheme and useIsDarkTheme to track theme changes and post updates to a webview.

```typescript
import { 
defineExtension
, 
useActiveColorTheme
, 
useIsDarkTheme
, 
watchEffect
 } from 'reactive-vscode'
import { 
useDemoWebviewView
 } from './webviewView'

export = 
defineExtension
(() => {
  const 
theme
 = 
useActiveColorTheme
()
  const 
isDark
 = 
useIsDarkTheme
()

  const 
webviewView
 = 
useDemoWebviewView
()

  
watchEffect
(() => {
    
webviewView
.
postMessage
({
      
type
: 'updateTheme',
      
isDark
: 
isDark
.
value
,
    })
  })
})
```

--------------------------------

### useAbsoluteUri

Source: https://kermanx.com/reactive-vscode/functions/useAbsoluteUri

A reactive utility function that resolves an absolute path from the extension context.

```APIDOC
## useAbsoluteUri

### Description
Reactive API for ExtensionContext.asAbsolutePath. This utility allows for the reactive resolution of absolute paths within the VSCode extension environment.

### Usage
This function acts as a reactive wrapper for the standard `ExtensionContext.asAbsolutePath` method.
```

--------------------------------

### Implement dynamic file watching with standard VSCode API

Source: https://kermanx.com/reactive-vscode/examples/fs-watcher/index.html

Manually manages a Map of FileSystemWatcher instances and handles lifecycle events like activation and deactivation.

```typescript
import type { ExtensionContext, FileSystemWatcher, 
Uri
 } from 'vscode'
import { commands, window, workspace } from 'vscode'

const 
watchers
 = new 
Map
<string, FileSystemWatcher>()

function 
addPattern
(
pattern
: string) {
  if (!
watchers
.
has
(
pattern
)) {
    const 
watcher
 = workspace.
createFileSystemWatcher
(
pattern
)
    
watcher
.
onDidChange
((
uri
: 
Uri
) => window.
showInformationMessage
(`File changed: ${
uri
}`))
    
watchers
.
set
(
pattern
, 
watcher
)
  }
}

function 
removePattern
(
pattern
: string) {
  const 
watcher
 = 
watchers
.
get
(
pattern
)
  if (
watcher
) {
    
watcher
.
dispose
()
    
watchers
.
delete
(
pattern
)
  }
}

export function 
activate
(
extensionContext
: ExtensionContext) {
  
addPattern
('src/**/*')
  
addPattern
('docs/**/*')

  
extensionContext
.
subscriptions
.
push
(
    commands.
registerCommand
('demo.add-watch-dir', async () => {
      const 
value
 = await window.
showInputBox
({ 
prompt
: 'Enter a glob' })
      if (
value
)
        
addPattern
(
value
)
    }),
    commands.
registerCommand
('demo.remove-watch-dir', async () => {
      const 
value
 = await window.
showInputBox
({ 
prompt
: 'Enter a glob' })
      if (
value
)
        
removePattern
(
value
)
    }),
  )
}

export function 
deactivate
() {
  for (const 
watcher
 of 
watchers
.
values
()) {
    
watcher
.
dispose
()
  }
}
```

--------------------------------

### useWebviewView

Source: https://kermanx.com/reactive-vscode/functions/useWebviewView

A reactive hook that serves as an interface for window.registerWebviewViewProvider, allowing developers to manage webview views in a reactive manner.

```APIDOC
## useWebviewView

### Description
Reactive API wrapper for `window.registerWebviewViewProvider`. This function allows for the registration of webview view providers using the Reactive VSCode framework.

### Usage
`useWebviewView(viewId, provider)`

### Parameters
- **viewId** (string) - The unique identifier for the webview view.
- **provider** (WebviewViewProvider) - The provider implementation to be registered.
```

--------------------------------

### useWindowState

Source: https://kermanx.com/reactive-vscode/functions/useWindowState

A reactive hook that tracks the current state of the VSCode window.

```APIDOC
## useWindowState

### Description
Provides a reactive interface for the VSCode `window.state` property. This allows components or services to reactively observe changes in the window's state.

### Signature
`useWindowState(): ReactiveState`

### Returns
- **ReactiveState** (Object) - A reactive object reflecting the current `window.state` properties.
```

--------------------------------

### Implement Editor Decorations with Original VSCode API

Source: https://kermanx.com/reactive-vscode/examples/editor-decoration

Uses standard imperative API to manage decorations, requiring manual subscription management for configuration and editor changes.

```typescript
import type { ExtensionContext } from 'vscode'
import { window, workspace } from 'vscode'

const 
decorationType
 = window.
createTextEditorDecorationType
({
  
backgroundColor
: 'red',
})

function 
updateDecorations
(
enabled
: boolean) {
  window.
activeTextEditor
?.
setDecorations
(
    
decorationType
,
    
enabled
 ? [/* ... Caclulated ranges ... */] : [],
  )
}

export function 
activate
(
context
: ExtensionContext) {
  const 
configurations
 = workspace.
getConfiguration
('demo')
  let 
decorationsEnabled
 = 
configurations
.
get
<boolean>('decorations')!

  
context
.
subscriptions
.
push
(workspace.
onDidChangeConfiguration
((
e
) => {
    if (
e
.
affectsConfiguration
('demo.decorations')) {
      
decorationsEnabled
 = 
configurations
.
get
<boolean>('decorations')!
      
updateDecorations
(
decorationsEnabled
)
    }
  }))
  
context
.
subscriptions
.
push
(window.
onDidChangeActiveTextEditor
(() => {
    
updateDecorations
(
decorationsEnabled
)
  }))

  
updateDecorations
(
decorationsEnabled
)
}
```

--------------------------------

### Define commands in package.json

Source: https://kermanx.com/reactive-vscode/guide/command.html

Register commands in the contributes.commands field of the extension manifest.

```json
{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}
```

--------------------------------

### useFileSystemWatcher

Source: https://kermanx.com/reactive-vscode/functions/useFileSystemWatcher

A reactive hook that allows monitoring of file system events in a VSCode workspace.

```APIDOC
## useFileSystemWatcher

### Description
Reactive API for workspace.createFileSystemWatcher. This function allows developers to observe file system changes reactively within the VSCode workspace environment.

### Signature
`useFileSystemWatcher(globPattern, ignoreCreateEvents?, ignoreChangeEvents?, ignoreDeleteEvents?)`

### Parameters
- **globPattern** (string) - Required - A glob pattern that defines the files to watch.
- **ignoreCreateEvents** (boolean) - Optional - Whether to ignore file creation events.
- **ignoreChangeEvents** (boolean) - Optional - Whether to ignore file change events.
- **ignoreDeleteEvents** (boolean) - Optional - Whether to ignore file deletion events.
```

--------------------------------

### Define Custom Contexts with useVscodeContext

Source: https://kermanx.com/reactive-vscode/guide/context.html

Demonstrates defining contexts using static values, refs, and computed getters. Contexts defined as refs can be updated manually, while those using getters update automatically.

```typescript
import { 
computed
, 
defineExtension
, 
ref
, 
useVscodeContext
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
contextA
 = 
useVscodeContext
('demo.fromValue', true) 
  const 
contextB
 = 
useVscodeContext
('demo.fromRef', 
contextA
) 
  const 
contextC
 = 
useVscodeContext
('demo.fromGetter', () => !
contextA
.
value
) 
})
```

--------------------------------

### useLogLevel()

Source: https://kermanx.com/reactive-vscode/functions/useLogLevel

A reactive hook that tracks the current log level of the VSCode environment.

```APIDOC
## useLogLevel

### Description
Provides a reactive interface for the `env.logLevel` property in the VSCode API. This allows for automatic updates when the environment log level changes.

### Signature
`useLogLevel(): LogLevel`

### Returns
- **LogLevel** (enum) - The current log level of the VSCode environment.
```

--------------------------------

### useStatusBarItem

Source: https://kermanx.com/reactive-vscode/functions/useStatusBarItem

A reactive hook that provides an interface for creating and managing status bar items in VSCode.

```APIDOC
## useStatusBarItem

### Description
Reactive API wrapper for the VSCode `window.createStatusBarItem` function. It allows for the creation and management of status bar items in a reactive manner.

### Category
window
```

--------------------------------

### useViewVisibility

Source: https://kermanx.com/reactive-vscode/functions/useViewVisibility

A reactive hook to track the visibility of a VSCode view.

```APIDOC
## useViewVisibility

### Description
Reactive API for tracking the visibility state of a `TreeView` or `WebviewView` in VSCode.

### Usage
```typescript
const isVisible = useViewVisibility(view);
```

### Parameters
- **view** (TreeView | WebviewView) - Required - The VSCode view instance to monitor.

### Returns
- **isVisible** (boolean) - The current visibility state of the provided view.
```

--------------------------------

### useInputBox

Source: https://kermanx.com/reactive-vscode/functions/useInputBox

A reactive hook that provides an interface for creating and managing input boxes within the VSCode environment.

```APIDOC
## useInputBox

### Description
Provides a reactive wrapper for the `window.createInputBox` API in VSCode.

### Usage
`useInputBox()`

### Returns
- **InputBox** (Object) - A reactive instance representing the input box created via `window.createInputBox`.
```

--------------------------------

### Generate configuration types with vscode-ext-gen

Source: https://kermanx.com/reactive-vscode/guide/config.html

Use generated metadata from vscode-ext-gen to define configuration types.

```ts
// ./generated-meta.ts is generated by vscode-ext-gen

import type { NestedScopedConfigs } from './generated-meta'
import { 
defineConfig
 } from 'reactive-vscode'
import { 
scopedConfigs
 } from './generated-meta'

const 
config
 = 
defineConfig
<NestedScopedConfigs>(
scopedConfigs
.
scope
)
```

--------------------------------

### Compare reactive-vscode and Original VSCode API

Source: https://kermanx.com/reactive-vscode/guide/why.html

A comparison showing how reactive-vscode simplifies editor decoration logic compared to the standard imperative VSCode API approach.

```typescript
import { 
defineConfig
, 
defineExtension
, 
useActiveTextEditor
, 
useEditorDecorations
 } from 'reactive-vscode'

const 
config
 = 
defineConfig
<{ 
decorations
: boolean }>('demo')

export = 
defineExtension
(() => {
  const 
editor
 = 
useActiveTextEditor
()
  
useEditorDecorations
(
    
editor
,
    {
      
backgroundColor
: 'red',
    },
    () => 
config
.
decorations
 ? [/* ... Caclulated ranges ... */] : [],
  )
})
```

```typescript
import type { ExtensionContext } from 'vscode'
import { window, workspace } from 'vscode'

const 
decorationType
 = window.
createTextEditorDecorationType
({
  
backgroundColor
: 'red',
})

function 
updateDecorations
(
enabled
: boolean) {
  window.
activeTextEditor
?.
setDecorations
(
    
decorationType
,
    
enabled
 ? [/* ... Caclulated ranges ... */] : [],
  )
}

export function 
activate
(
context
: ExtensionContext) {
  const 
configurations
 = workspace.
getConfiguration
('demo')
  let 
decorationsEnabled
 = 
configurations
.
get
<boolean>('decorations')!

  
context
.
subscriptions
.
push
(workspace.
onDidChangeConfiguration
(((
e
) => {
    if (
e
.
affectsConfiguration
('demo.decorations')) {
      
decorationsEnabled
 = 
configurations
.
get
<boolean>('decorations')!
      
updateDecorations
(
decorationsEnabled
)
    }
  }))
  
context
.
subscriptions
.
push
(window.
onDidChangeActiveTextEditor
(() => {
    
updateDecorations
(
decorationsEnabled
)
  }))

  
updateDecorations
(
decorationsEnabled
)
}
```

--------------------------------

### Implement a counter with Original VSCode API

Source: https://kermanx.com/reactive-vscode/examples/hello-counter

Uses the standard VSCode extension API to manually manage state and status bar subscriptions.

```typescript
import type { ExtensionContext } from 'vscode'
import { commands, 
StatusBarAlignment
, window } from 'vscode'

export function 
activate
(
extensionContext
: ExtensionContext) {
  let 
counter
 = 0

  const 
item
 = window.
createStatusBarItem
(
StatusBarAlignment
.
Right
, 100)

  function 
updateStatusBar
() {
    
item
.
text
 = `$(megaphone) Hello*${
counter
}`
    
item
.
show
()
  }

  
updateStatusBar
()

  
extensionContext
.
subscriptions
.
push
(
    commands.
registerCommand
('extension.sayHello', () => {
      
counter
++
      
updateStatusBar
()
    }),
    commands.
registerCommand
('extension.sayGoodbye', () => {
      
counter
--
      
updateStatusBar
()
    }),
  )
}
```

--------------------------------

### Register commands with useCommand

Source: https://kermanx.com/reactive-vscode/guide/command.html

Use the useCommand hook within defineExtension to bind logic to a command ID.

```ts
import { 
defineExtension
, 
ref
, 
useCommand
, 
watchEffect
 } from 'reactive-vscode'
import { window } from 'vscode'

export = 
defineExtension
(() => {
  const 
helloCounter
 = 
ref
(0)
  
useCommand
('extension.sayHello', () => {
    window.
showInformationMessage
('Hello World')
    
helloCounter
.
value
++
  })

  
watchEffect
(() => {
    if (
helloCounter
.
value
 > 99)
      window.
showWarningMessage
('You have said hello too many times!')
  })
})
```

--------------------------------

### Monitor Window State

Source: https://kermanx.com/reactive-vscode/guide/window.html

Tracks window activity and focus status using the useWindowState composable.

```typescript
import { 
defineExtension
, 
useWindowState
, 
watchEffect
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const { 
active
: 
isWindowActive
, 
focused
: 
isWindowFocused
 } = 
useWindowState
()

  
watchEffect
(() => {
    
console
.
log
('Window is active:', 
isWindowActive
.
value
)
    
console
.
log
('Window is focused:', 
isWindowFocused
.
value
)
  })
})
```

--------------------------------

### useActiveTerminal

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Retrieves the currently active terminal in a reactive way.

```APIDOC
## useActiveTerminal()

### Description
Returns a ShallowRef containing the currently active terminal or undefined if none is active.
```

--------------------------------

### useDocumentText

Source: https://kermanx.com/reactive-vscode/functions/useDocumentText

A reactive hook that tracks and returns the text content of a given VSCode TextDocument.

```APIDOC
## useDocumentText

### Description
Provides a reactive interface to access the text content of a VSCode TextDocument. This hook automatically updates when the underlying document text changes.

### Signature
`useDocumentText(document: TextDocument): string`

### Parameters
- **document** (TextDocument) - Required - The VSCode TextDocument instance to observe.

### Returns
- **string** - The current text content of the document.
```

--------------------------------

### useVisibleNotebookEditors

Source: https://kermanx.com/reactive-vscode/functions/useVisibleNotebookEditors

A reactive hook that tracks the currently visible notebook editors in the VSCode window.

```APIDOC
## useVisibleNotebookEditors

### Description
Provides a reactive interface to the VSCode `window.visibleNotebookEditors` API. This hook allows tracking the list of notebook editors that are currently visible in the editor area.

### Signature
`useVisibleNotebookEditors(): NotebookEditor[]`

### Returns
- **NotebookEditor[]** - An array of currently visible notebook editors.
```

--------------------------------

### Implement dynamic file watching with reactive-vscode

Source: https://kermanx.com/reactive-vscode/examples/fs-watcher/index.html

Uses useFileSystemWatcher and a reactive Set to manage file patterns dynamically. The watcher automatically updates when the reactive set changes.

```typescript
import { 
defineExtension
, 
reactive
, 
useCommands
, 
useFileSystemWatcher
 } from 'reactive-vscode'
import { window } from 'vscode'

export = 
defineExtension
(() => {
  const 
globs
 = 
reactive
(new 
Set
(['src/**/*', 'docs/**/*']))
  const 
watcher
 = 
useFileSystemWatcher
(
globs
)
  
watcher
.
onDidChange
(
uri
 => window.
showInformationMessage
(`File changed: ${
uri
}`))

  
useCommands
({
    'demo.add-watch-dir': async () => {
      const 
value
 = await window.
showInputBox
({ 
prompt
: 'Enter a glob' })
      if (
value
)
        
globs
.
add
(
value
)
    },
    'demo.remove-watch-dir': async () => {
      const 
value
 = await window.
showInputBox
({ 
prompt
: 'Enter a glob' })
      if (
value
)
        
globs
.
delete
(
value
)
    },
  })
})
```

--------------------------------

### Watch File System Changes

Source: https://kermanx.com/reactive-vscode/guide/window.html

Monitors specific file patterns for changes using useFileSystemWatcher.

```typescript
import { 
computed
, 
defineExtension
, 
useFileSystemWatcher
, 
watchEffect
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
filesToWatch
 = 
computed
(() => ['**/*.md', '**/*.txt'])
  const 
watcher
 = 
useFileSystemWatcher
(
filesToWatch
)
  
watcher
.
onDidChange
((
uri
) => {
    
console
.
log
('File changed:', 
uri
)
  })
})
```

--------------------------------

### Register a Tree View with useTreeView

Source: https://kermanx.com/reactive-vscode/guide/view.html

Define a hierarchical tree structure using reactive data and the useTreeView composable.

```ts
import type { TreeViewNode } from 'reactive-vscode'
import { 
computed
, 
defineService
, 
useTreeView
 } from 'reactive-vscode'
import { 
TreeItemCollapsibleState
 } from 'vscode'

export const 
useDemoTreeView
 = 
defineService
(() => {
  function 
getRootNode
(
index
: number) {
    return {
      
children
: [
        
getChildNode
(
index
 * 10 + 1),
        
getChildNode
(
index
 * 10 + 2),
      ],
      
treeItem
: {
        
label
: `Root ${
index
}`,
        
collapsibleState
: 
TreeItemCollapsibleState
.
Expanded
,
      },
    }
  }

  function 
getChildNode
(
index
: number) {
    return {
      
treeItem
: {
        
label
: `Child ${
index
}`,
        
collapsibleState
: 
TreeItemCollapsibleState
.
None
,
      },
    }
  }

  const 
treeData
 = 
computed
(() => {
    const 
roots
: TreeViewNode[] = []
    for (let 
i
 = 1; 
i
 < 5; 
i
++)
      
roots
.
push
(
getRootNode
(
i
))
    return 
roots

  })

  const 
view
 = 
useTreeView
(
    'reactive-tree-view',
    
treeData
,
    {
      
title
: () => `Tree with ${
treeData
.
value
.
length
} roots`,
    },
  )

  // return anything you want to expose
  return 
view

})
```

```ts
import { 
defineExtension
 } from 'reactive-vscode'
import { 
useDemoTreeView
 } from './treeView'

export = 
defineExtension
(() => {
  const 
demoTreeView
 = 
useDemoTreeView
()
  // ...
})
```

--------------------------------

### useOpenedTerminals

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Retrieves a list of all currently open terminals.

```APIDOC
## useOpenedTerminals()

### Description
Returns a ShallowRef containing an array of all currently open terminals.
```

--------------------------------

### useActiveColorTheme

Source: https://kermanx.com/reactive-vscode/functions/useActiveColorTheme

A reactive hook that tracks the current active color theme of the VSCode window.

```APIDOC
## useActiveColorTheme

### Description
A reactive API wrapper for `window.activeColorTheme`. This hook allows components to reactively track the current color theme applied in the VSCode window.

### Usage
```typescript
const activeTheme = useActiveColorTheme();
```
```

--------------------------------

### Implement Editor Decorations with Reactive VSCode

Source: https://kermanx.com/reactive-vscode/examples/editor-decoration

Uses reactive hooks to manage editor decorations based on configuration changes.

```typescript
import { 
defineConfig
, 
defineExtension
, 
useActiveTextEditor
, 
useEditorDecorations
 } from 'reactive-vscode'

const 
config
 = 
defineConfig
<{ 
decorations
: boolean }>('demo')

export = 
defineExtension
(() => {
  const 
editor
 = 
useActiveTextEditor
()
  
useEditorDecorations
(
    
editor
,
    {
      
backgroundColor
: 'red',
    },
    () => 
config
.
decorations
 ? [/* ... Caclulated ranges ... */] : [],
  )
})
```

--------------------------------

### useL10nText

Source: https://kermanx.com/reactive-vscode/functions/useL10nText

A reactive hook that provides access to localized text, serving as a reactive interface for the standard l10n.t function.

```APIDOC
## useL10nText

### Description
Provides a reactive implementation of the `l10n.t` localization function. This hook allows components to automatically re-render or update when localization strings change.

### Usage
```typescript
const localizedText = useL10nText(message, ...args);
```

### Parameters
- **message** (string) - The localization key or message string to be translated.
- **args** (any[]) - Optional arguments to be passed to the localization function for interpolation.
```

--------------------------------

### useVscodeContext

Source: https://kermanx.com/reactive-vscode/functions/useVscodeContext

A hook used to reactively set a VS Code context for custom when clauses.

```APIDOC
## useVscodeContext

### Description
Reactively sets a VS Code context. This is used to define custom when clause contexts within a VS Code extension.

### Usage
```typescript
useVscodeContext(key: string, value: any);
```

### Parameters
- **key** (string) - Required - The identifier for the context key.
- **value** (any) - Required - The value to assign to the context key.
```

--------------------------------

### Access extension context

Source: https://kermanx.com/reactive-vscode/guide/extension.html

Accessing the global extensionContext object provided by reactive-vscode.

```typescript
import { 
extensionContext
 } from 'reactive-vscode'


extensionContext
.
value
?.
extensionPath
```

--------------------------------

### Define a VSCode extension

Source: https://kermanx.com/reactive-vscode/guide/extension.html

Basic structure for defining an extension using the defineExtension function.

```typescript
import { 
defineExtension
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  // Setup your extension here
})
```

```typescript
import { 
defineExtension
 } from 'reactive-vscode'

const { 
activate
, 
deactivate
 } = 
defineExtension
(() => {
  // Your extension code here
})
export { 
activate
, 
deactivate
 }
```

--------------------------------

### useWindowFocused()

Source: https://kermanx.com/reactive-vscode/functions/useWindowFocused

A reactive hook that returns the current focus state of the VSCode window.

```APIDOC
## useWindowFocused()

### Description
Returns a reactive boolean indicating whether the VSCode window is currently focused. This hook tracks the `window.state.focused` property.

### Returns
- **boolean** - True if the window is focused, false otherwise.
```

--------------------------------

### useTerminal

Source: https://kermanx.com/reactive-vscode/functions/useTerminal

A reactive hook that provides an interface for creating and managing VSCode terminals.

```APIDOC
## useTerminal

### Description
Reactive API wrapper for the VSCode `window.createTerminal` function.

### Usage
This function allows for reactive management of terminals within the VSCode environment.
```

--------------------------------

### useTerminalState

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Observes the state of a specific terminal.

```APIDOC
## useTerminalState(terminal: Terminal | () => Terminal | undefined)

### Description
Returns a ComputedRef containing the state of the provided terminal or a terminal resolved from a getter function.
```

--------------------------------

### Reactive API Hooks

Source: https://kermanx.com/reactive-vscode/functions

The library provides a comprehensive set of hooks to interact with the VS Code API reactively. These functions are categorized by their domain, such as chat, commands, editor, workspace, and window management.

```APIDOC
## Reactive API Functions

### Overview
The Reactive VSCode library exposes various hooks that mirror standard VS Code API functionality with reactive capabilities. These include:

- **Chat**: `useChatParticipant`
- **Commands**: `useCommand`, `useCommands`, `useTextEditorCommand`, `useTextEditorCommands`
- **Debug**: `useActiveDebugSession`
- **Document**: `useDocumentText`
- **Editor**: `useActiveNotebookEditor`, `useActiveTextEditor`, `useEditorDecorations`, `useNotebookEditorSelection`, `useNotebookEditorSelections`, `useNotebookEditorVisibleRanges`, `useTextEditorSelection`, `useTextEditorSelections`, `useTextEditorViewColumn`, `useTextEditorVisibleRanges`, `useVisibleNotebookEditors`, `useVisibleTextEditors`
- **Environment**: `useEnvShell`, `useIsTelemetryEnabled`, `useLogLevel`
- **Extension**: `useAllExtensions`, `useExtensionSecret`, `useGlobalState`, `useWorkspaceState`
- **Localization**: `useL10nText`
- **Lifecycle**: `useDisposable`, `useVscodeContext`, `defineConfig`, `defineService`
- **Language Models**: `useLmTools`
- **Tasks**: `useTaskExecutions`
- **Terminal**: `useActiveTerminal`, `useOpenedTerminals`, `useTerminal`, `useTerminalShellIntegration`, `useTerminalState`
- **Utilities**: `useAbsoluteUri`, `useEvent`, `useEventEmitter`
- **View**: `useTreeView`, `useViewVisibility`, `useWebviewPanel`, `useWebviewView`, `defineLogger`
- **Window**: `useActiveColorTheme`, `useInputBox`, `useIsDarkTheme`, `useQuickPick`, `useStatusBarItem`, `useWindowActive`, `useWindowFocused`, `useWindowState`
- **Workspace**: `useFileSystemWatcher`, `useWorkspaceFolders`
```

--------------------------------

### useVisibleTextEditors()

Source: https://kermanx.com/reactive-vscode/functions/useVisibleTextEditors

A reactive hook that tracks the state of window.visibleTextEditors in the VSCode API.

```APIDOC
## useVisibleTextEditors

### Description
Reactive API for accessing and tracking the `window.visibleTextEditors` property from the VSCode API.

### Usage
```typescript
const visibleEditors = useVisibleTextEditors();
```
```

--------------------------------

### useExtensionSecret(key: string)

Source: https://kermanx.com/reactive-vscode/functions/useExtensionSecret

Retrieves a reactive secret value from the extension's secrets storage. Returns null if the value is loading, or undefined if no value exists for the provided key.

```APIDOC
## useExtensionSecret

### Description
Retrieves a reactive secret value from the extension's secrets storage. This hook allows components to reactively track changes to specific secrets.

### Parameters
- **key** (string) - Required - The identifier for the secret to retrieve.

### Returns
- **value** (string | null | undefined) - Returns the secret value if found, null if the value is still loading, or undefined if the key does not exist.
```

--------------------------------

### useActiveNotebookEditor

Source: https://kermanx.com/reactive-vscode/functions/useActiveNotebookEditor

A reactive hook that provides access to the active notebook editor instance within the VSCode environment.

```APIDOC
## useActiveNotebookEditor

### Description
Provides a reactive interface for accessing the `window.activeNotebookEditor` property in the VSCode API. This hook allows components to reactively track changes to the currently active notebook editor.

### Usage
```typescript
const activeNotebookEditor = useActiveNotebookEditor();
```
```

--------------------------------

### Create event emitters with useEventEmitter

Source: https://kermanx.com/reactive-vscode/guide/event.html

Creates a friendly event emitter that extends the standard EventEmitter functionality.

```typescript
import { 
defineExtension
, 
useEventEmitter
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
myEvent
 = 
useEventEmitter
<string>([/* optional listenrs */])

  
someVscodeApi
({
    
onSomeEvent
: 
myEvent
.
event
,
  })

  
myEvent
.
event
((msg) => {
    
console
.
log
('Received message:', 
msg
)
  })

  
myEvent
.
fire
('Hello, World!')
})
```

--------------------------------

### Convert raw events to friendly emitters

Source: https://kermanx.com/reactive-vscode/guide/event.html

Wraps an existing raw event emitter into a friendly reactive-vscode event emitter.

```typescript
import { 
defineExtension
, 
useEventEmitter
 } from 'reactive-vscode'
import { 
EventEmitter
 } from 'vscode'

export = 
defineExtension
(() => {
  const 
rawEvent
 = new 
EventEmitter
<string>()
  const 
myEvent
 = 
useEventEmitter
(
rawEvent
, [/* optional listenrs */])
})
```

--------------------------------

### Add editor decorations with useEditorDecorations

Source: https://kermanx.com/reactive-vscode/guide/editor.html

Apply visual decorations to an editor using useEditorDecorations, providing a decoration type and dynamic ranges.

```ts
import { 
defineExtension
, 
useActiveTextEditor
, 
useEditorDecorations
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
editor
 = 
useActiveTextEditor
()
  
useEditorDecorations
(
    
editor
,
    { 
backgroundColor
: 'red' }, // Or created decoration type
    () => [/* Dynamic calculated ranges */] // Or Ref/Computed
  )
})
```

--------------------------------

### useWorkspaceFolders()

Source: https://kermanx.com/reactive-vscode/functions/useWorkspaceFolders

A reactive hook that returns the current list of workspace folders. It automatically updates when the workspace folders change.

```APIDOC
## useWorkspaceFolders()

### Description
Provides a reactive wrapper around the VSCode `workspace.workspaceFolders` API. It returns the current array of workspace folders and triggers updates whenever the workspace configuration changes.

### Signature
`useWorkspaceFolders(): WorkspaceFolder[] | undefined`

### Returns
- **WorkspaceFolder[] | undefined** - An array of workspace folders currently open in the workspace, or undefined if no workspace is open.
```

--------------------------------

### useIsTelemetryEnabled

Source: https://kermanx.com/reactive-vscode/functions/useIsTelemetryEnabled

A reactive hook that tracks the state of the VSCode telemetry setting.

```APIDOC
## useIsTelemetryEnabled

### Description
Provides a reactive wrapper for the VSCode `env.isTelemetryEnabled` property, allowing components to react to changes in telemetry settings.

### Usage
```typescript
const isEnabled = useIsTelemetryEnabled();
```

### Returns
- **isEnabled** (boolean) - The current telemetry enabled status.
```

--------------------------------

### List All Terminals with useOpenedTerminals

Source: https://kermanx.com/reactive-vscode/guide/terminal.html

Retrieves a reactive list of all currently open terminals.

```typescript
import { 
defineExtension
, 
useOpenedTerminals
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
terminals
 = 
useOpenedTerminals
() 
})
```

--------------------------------

### Implement a counter with Reactive VSCode

Source: https://kermanx.com/reactive-vscode/examples/hello-counter

Uses the reactive-vscode API to manage state and status bar updates declaratively.

```typescript
import { 
defineExtension
, 
ref
, 
useCommands
, 
useStatusBarItem
 } from 'reactive-vscode'
import { 
StatusBarAlignment
 } from 'vscode'

export = 
defineExtension
(() => {
  const 
counter
 = 
ref
(0)

  
useStatusBarItem
({
    
alignment
: 
StatusBarAlignment
.
Right
,
    
priority
: 100,
    
text
: () => `$(megaphone) Hello*${
counter
.
value
}`,
  })

  
useCommands
({
    'extension.sayHello': () => 
counter
.
value
++,
    'extension.sayGoodbye': () => 
counter
.
value
--,
  })
})
```

--------------------------------

### useActiveTerminal

Source: https://kermanx.com/reactive-vscode/functions/useActiveTerminal

A reactive hook that tracks the state of the active terminal in VSCode.

```APIDOC
## useActiveTerminal

### Description
Provides a reactive wrapper for the VSCode `window.activeTerminal` API. It allows components to reactively track changes to the currently active terminal.

### Usage
```typescript
const activeTerminal = useActiveTerminal();
```

### Returns
- **activeTerminal** (Terminal | undefined) - The currently active terminal instance or undefined if no terminal is active.
```

--------------------------------

### useTextEditorSelection

Source: https://kermanx.com/reactive-vscode/functions/useTextEditorSelection

A reactive hook that tracks the selection state of a VSCode TextEditor.

```APIDOC
## useTextEditorSelection

### Description
Provides a reactive wrapper for the VSCode `TextEditor.selection` property, allowing components to reactively track changes to the editor selection.

### Usage
```typescript
const selection = useTextEditorSelection();
```
```

--------------------------------

### Detect theme changes with Original VSCode API

Source: https://kermanx.com/reactive-vscode/examples/theme-detector/index.html

Uses the standard VS Code API to manually listen for theme changes via onDidChangeActiveColorTheme.

```typescript
import type { ExtensionContext } from 'vscode'
import { 
ColorThemeKind
, window } from 'vscode'

function 
showMessage
() {
  const 
theme
 = window.
activeColorTheme

  const 
isDark
 = 
theme
.
kind
 === 
ColorThemeKind
.
Dark
 || 
theme
.
kind
 === 
ColorThemeKind
.
HighContrast

  window.
showInformationMessage
(`Your theme is ${
theme
} (kind: ${
isDark
 ? 'dark' : 'light'})`)
}

export function 
activate
(
extensionContext
: ExtensionContext) {
  
showMessage
()
  
extensionContext
.
subscriptions
.
push
(window.
onDidChangeActiveColorTheme
(
showMessage
))
}
```

--------------------------------

### Hide commands from Command Palette

Source: https://kermanx.com/reactive-vscode/guide/command.html

Set the contributes.menus.commandPalette when property to false to prevent a command from appearing in the palette.

```json
{
  "contributes": {
    "commands": [
      {
        "command": "extension.doSomething",
        "title": "This requires params"
      }
    ],
    "menus": {
      "commandPalette": [
        {
          "command": "extension.doSomething",
          "when": "false"
        }
      ]
    }
  }
}
```

--------------------------------

### Access Workspace Folders

Source: https://kermanx.com/reactive-vscode/guide/window.html

Retrieves the current list of workspace folders using useWorkspaceFolders.

```typescript
import { 
defineExtension
, 
useWorkspaceFolders
, 
watchEffect
 } from 'reactive-vscode'

export = 
defineExtension
(() => {
  const 
workspaceFolders
 = 
useWorkspaceFolders
()

  
watchEffect
(() => {
    
console
.
log
('There are', 
workspaceFolders
.
value
?.
length
, 'workspace folders')
  })
})
```

--------------------------------

### Configure TypeScript for CommonJS

Source: https://kermanx.com/reactive-vscode/guide/extension.html

Required tsconfig.json settings when using a bundler to support CommonJS modules.

```json
{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "Preserve"
  }
}
```

--------------------------------

### useActiveTextEditor()

Source: https://kermanx.com/reactive-vscode/functions/useActiveTextEditor

A reactive hook that returns the current active text editor instance. It updates automatically when the active editor changes in the VSCode window.

```APIDOC
## useActiveTextEditor

### Description
Provides a reactive reference to the VSCode `window.activeTextEditor`. This hook allows components to reactively track changes to the currently focused text editor.

### Signature
`useActiveTextEditor(): TextEditor | undefined`

### Returns
- **TextEditor | undefined** - The currently active text editor, or undefined if no editor is active.
```

--------------------------------

### useActiveDebugSession

Source: https://kermanx.com/reactive-vscode/functions/useActiveDebugSession

A reactive hook that tracks the currently active debug session.

```APIDOC
## useActiveDebugSession

### Description
A reactive hook that provides access to the current `debug.activeDebugSession` from the VSCode API. It updates automatically when the active debug session changes.

### Signature
`useActiveDebugSession(): DebugSession | undefined`

### Returns
- **DebugSession** (object) - The currently active debug session, or undefined if no session is active.
```

--------------------------------

### Convert raw VSCode events with useEvent

Source: https://kermanx.com/reactive-vscode/guide/event.html

Converts a raw VSCode event into an auto-disposed event, eliminating the need for manual disposal.

```typescript
import { 
defineExtension
, 
useEvent
 } from 'reactive-vscode'
import { workspace } from 'vscode'

const 
onDidCreateFiles
 = 
useEvent
(workspace.
onDidCreateFiles
)

export = 
defineExtension
(() => {
  // No need to dispose the event
  
onDidCreateFiles
((e) => {
    
console
.
log
('Files created:', 
e
.
files
)
  })
})
```
Tokens:
Raw