vsix-utils/dist/manifest.d.ts

utilities for working with VSIX packages

import { Manifest, ExtensionKind } from './types.js';

/**
 * @module manifest
 *
 * This module contains utility functions for manifests.
 *
 * @example
 * ```ts
 * import { readProjectManifest } from "vsix-utils";
 *
 * const projectManifest = await readProjectManifest('/path/to/project');
 *
 * if (projectManifest != null) {
 *   console.log("an error occurred while reading the project manifest");
 * }
 *
 * const { fileName, manifest } = projectManifest;
 *
 * console.log(fileName); // Outputs: /path/to/project/package.json
 * console.log(manifest); // Outputs: Parsed content of package.json
 * ```
 *
 * @example
 * ```ts
 * import { createVsixManifest, readProjectManifest } from "vsix-utils";
 *
 * const projectManifest = await readProjectManifest('/path/to/project');
 *
 * if (projectManifest != null) {
 *   console.log("an error occurred while reading the project manifest");
 * }
 *
 * const { fileName, manifest } = projectManifest;
 *
 * const vsixManifest = createVsixManifest(manifest, {
 *   assets: [
 *     { type: "Microsoft.VisualStudio.Services.Icons.Default", path: "icon.png" },
 *   ]
 * });
 * ```
 */

/**
 * Represents the project manifest.
 */
interface ProjectManifest {
    /**
     * The file name of the project manifest.
     */
    fileName: string;
    /**
     * The parsed content of the project manifest.
     */
    manifest: Manifest;
}
/**
 * Reads the project manifest (package.json) from the specified project directory.
 *
 * @param {string} projectDir - The directory of the project where the package.json is located.
 * @returns {Promise<ProjectManifest | null>} A promise that resolves to an object containing the file name and the parsed manifest content, or null if the manifest could not be read.
 *
 * @example
 * ```ts
 * const { fileName, manifest } = await readProjectManifest('/path/to/project');
 * console.log(fileName); // Outputs: /path/to/project/package.json
 * console.log(manifest); // Outputs: Parsed content of package.json
 * ```
 */
declare function readProjectManifest(projectDir: string): Promise<ProjectManifest | null>;
type ManifestAssetType = "Microsoft.VisualStudio.Services.Icons.Default" | `Microsoft.VisualStudio.Code.Translation.${string}` | "Microsoft.VisualStudio.Services.Content.License" | "Microsoft.VisualStudio.Services.Content.Details" | "Microsoft.VisualStudio.Services.Content.Changelog";
/**
 * Represents an asset in the VSIX manifest.
 */
interface ManifestAsset {
    /**
     * The type of the asset.
     */
    type: ManifestAssetType;
    /**
     * The path to the asset.
     */
    path: string;
}
/**
 * Represents the options for creating a VSIX manifest.
 */
interface VsixManifestOptions {
    /**
     * Assets to include in the VSIX
     */
    assets?: ManifestAsset[];
    /**
     * The target platform for the extension.
     */
    target?: string;
    /**
     * The path to license file for the extension.
     */
    license?: string;
    /**
     * The path to the icon file for the extension.
     */
    icon?: string;
    /**
     * Tags for the extension.
     */
    tags?: string[];
    /**
     * Flags for the extension.
     */
    flags?: string[];
    /**
     * QnA link for customer support
     * @default false
     *
     * NOTE:
     * you can either set it to "marketplace" or a custom link.
     * If you set it to false, the QnA link will not be included in the manifest.
     */
    qna?: "marketplace" | (string & {}) | false;
    /**
     * Whether or not the extension is a pre-release version.
     * @default false
     */
    preRelease?: boolean;
}
declare function createVsixManifest(manifest: Manifest, options: VsixManifestOptions): string;
/**
 * Transforms an extension manifest to determine the appropriate extension kinds.
 * Extension kinds define where an extension can run (UI, workspace, web).
 *
 * The transformation follows these rules:
 * 1. Uses explicit extension kinds if specified in manifest
 * 2. Adds "web" kind if browser support is detected
 * 3. Determines kinds based on main entry point presence
 * 4. Handles extension packs and dependencies
 * 5. Filters kinds based on contribution points
 *
 * @param {Manifest} manifest - The extension manifest object to transform
 * @returns {ExtensionKind[]} An array of ExtensionKind values representing where the extension can run
 *
 * @example
 * ```ts
 * const manifest = {
 *   browser: "dist/web/extension.js",
 *   main: "dist/extension.js"
 * };
 *
 * transformExtensionKind(manifest); // Returns ["workspace", "web"]
 * ```
 */
declare function transformExtensionKind(manifest: Manifest): ExtensionKind[];
/**
 * Checks if an extension manifest includes web as a supported platform.
 * @param {Manifest} manifest - The extension manifest to check
 * @returns True if the extension supports web platform, false otherwise
 */
declare function isWebKind(manifest: Manifest): boolean;
/**
 * Extracts and generates an array of tags from a VS Code extension manifest.
 *
 * @param {Manifest} manifest - The VS Code extension manifest object
 * @returns {string[]} An array of unique strings representing tags for the extension
 */
declare function getManifestTags(manifest: Manifest): string[];

export { type ManifestAsset, type ManifestAssetType, type ProjectManifest, type VsixManifestOptions, createVsixManifest, getManifestTags, isWebKind, readProjectManifest, transformExtensionKind };