Manifest

The extension manifest extends the regular package.json format found in npm-managed JavaScript projects.

It contains information about dependencies, but also extension-specific fields such as what commands the extension exports, their preferences, arguments, etc.

Anatomy of a manifest

This is what the manifest from the create extension page looks like:

{
  "name": "my-first-extension",
  "title": "My First Extension",
  "description": "This is my very first extension",
  "categories": [],
  "license": "MIT",
  "author": "aurelle",
  "contributors": [],
  "pastContributors": [],
  "icon": "extension_icon.webp",
  "commands": [
    {
      "name": "my-first-command",
      "title": "My First Command",
      "subtitle": "My first subtitle",
      "description": "My first command description",
      "mode": "view"
    }
  ],
  "preferences": [],
  "scripts": {
    "build": "vici build",
    "dev": "vici develop"
  },
  "dependencies": {
    "@vicinae/api": "^0.8.2"
  },
  "devDependencies": {
    "typescript": "^5.9.2"
  }
}

Some fields are particularly interesting to us:

• name: the identifier of the extension, which should be in a sluggified format.
• title: the display name of an extension, which will be shown to users.
• author: the author of the extension. Needs to be a single username. This is used for a variety of things inside Vicinae.
• icon is used to resolve the extension's icon at runtime. Vicinae looks for it relative to the extension's assets directory. The same applies to command icons, if specified.
• commands lists all the available commands for this extension. The name key for each command should map to a proper command entrypoint under src. In this case, src/my-first-command.tsx is expected. At least one command should be specified to make it a valid extension.

Dealing with preferences

Anatomy of a preference object

An extension and each of its commands can declare preferences that must be set before they can run.

This is useful for requiring the user to provide an access token, tweaking command behavior, and more.

A preference object looks like this:

{
	"name": "access-token",
	"title": "Access Token",
	"description": "The access token required to access the service",
	"required": true,
	"type": "password"
}

• name is the identifier of the preference, which should remain in slugified form
• title is the display name of the preference, shown to users
• required indicates whether the preference must be set. If required and no default value is provided, Vicinae will ask the user to supply it before the command can start.
• type is the type of preference. Currently supported: textfield, password, checkbox, dropdown, file, and directory.

If a preference is of type dropdown an additional data field is expected:

{
  "name": "artwork",
  "title": "Artwork Style",
  "description": "Choose the preferred artwork style for Pokémon.",
  "required": false,
  "type": "dropdown",
  "default": "official",
  "data": [
	{
	  "title": "Official Artwork",
	  "value": "official"
	},
	{
	  "title": "Pixel Art",
	  "value": "pixel"
	}
  ]
} 

Add preferences

To specify extension preferences, fill in the top-level preferences array with preference objects.

You can do the same for each command inside commands to specify command-level preferences.