Configurations

An extension can contribute extension-specific settings.

Define in Manifest Non-Proprietary

To define the settings in the package.json, you need to add the contributes.configuration field. The configuration field is an object that contains the configuration settings.

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

Visit the official documentation for more information.

Use in Extension

To use the settings in the extension, you can use the defineConfigs or defineConfigObject function to define the configuration. The following examples are corresponding to the above configuration.

As Refs

import { defineConfigs } from 'reactive-vscode'

const { enable, greeting } = defineConfigs('your-extension', {
  enable: Boolean,
  greeting: [String, null],
})

Note that you should always set the default value in the manifest file. defineConfigs does not provide default values.

In the above example, enable is of type ConfigRef<boolean>, which extends Ref<boolean>.

import { ConfigurationTarget } from 'vscode'

// This will write the value back to the configuration.
enable.value = false

// To pass the rest of the options, you can use the `update` method.
enable.update(false, ConfigurationTarget.Global)

// Only set the ref value without writing back to the configuration.
enable.set(false)

Visit the official documentation for more information about the rest of the options.

As an Object

import { defineConfigObject } from 'reactive-vscode'

const config = defineConfigObject('your-extension', {
  enable: Boolean,
  greeting: [String, null],
})

In the above example, config is a ShallowReactive object.

import { ConfigurationTarget } from 'vscode'

// This will write the value back to the configuration.
config.enable = false

// To pass the rest of the options, you can use the `$update` method.
config.$update('enable', false, ConfigurationTarget.Global)

// Only set the ref value without writing back to the configuration.
config.$set('enable', false)

Visit the official documentation for more information about the rest of the options.

Use with vscode-ext-gen

You can also use the vscode-ext-gen to generate the configuration settings. For example:

import { defineConfigObject, defineConfigs, reactive, ref } from 'reactive-vscode'
import { type NestedScopedConfigs, scopedConfigs } from './generated-meta'

const config = defineConfigObject<NestedScopedConfigs>(
  scopedConfigs.scope,
  scopedConfigs.defaults,
)