@meanmail/devshift

DevShift Plugin Builder

A tool for building DevShift extensions for JetBrains IDEs.

Installation

npm install -g @meanmail/devshift

Or use it directly with npx:

npx @meanmail/devshift build <source-path> <output-path>

Usage

1. Create a directory for your extension with the following files:

   • extension.json: Contains metadata about your extension
   • extension.ts: Contains the code for your extension (will be compiled to extension.mjs)

2. Run the builder:

@meanmail/devshift build <source-path> <output-path>

Where:

• <source-path> is the path to the directory containing your extension files
• <output-path> is the path where the plugin will be generated

Extension Structure

extension.json

The extension.json file contains metadata about your extension:

{
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A description of my plugin",
  "author": "Your Name",
  "license": "MIT",
  "url": "https://example.com"
}

Required fields:

• id: Unique identifier for the plugin
• name: Display name of the plugin
• version: Version of the plugin
• description: Short description of the plugin
• author: Author of the plugin
• license: License of the plugin

Optional fields:

• url: URL for the plugin

extension.ts and extension.mjs

The extension.ts file contains the code for your extension, which will be compiled to extension.mjs. It should export two functions:

// ES module syntax - no need to import 'ide' as it's available in the global scope

export function activate() {
  // Called when the plugin is activated
  ide.showMessage('Hello!', 'Hello from the extension!')
}

export function deactivate() {
  // Called when the plugin is deactivated
  ide.showMessage('Goodbye!', 'Goodbye from the extension!')
}

IDE API

The following API is available to your extension through the global ide object:

showMessage(title: string, message: string): void

Shows an information message to the user.

• title: The title of the message
• message: The content of the message

Example:

ide.showMessage('Hello!', 'Hello from the extension!')

Building the Plugin

After running the builder, you'll get a directory structure that can be built using Gradle:

cd <output-path>/<plugin-name>
./gradlew buildPlugin

The built plugin will be available in the build/distributions directory.

Type Definitions

Type definitions for the IDE API are included in the package. To use them in your TypeScript project, add a reference to the types:

/// <reference path="node_modules/@meanmail/devshift/dist/types/ide-api.d.ts" />

Or import them directly:

import '@meanmail/devshift/dist/types/ide-api';

Development Tools

Type Checking

The project includes TypeScript for static type checking. You can run type checking without compiling the code using:

npm run type-check

This will help catch type errors before runtime.

Linting

ESLint is configured for code quality and consistency. You can run the linter using:

npm run lint

To automatically fix linting issues:

npm run lint:fix

The linting rules are configured in .eslintrc.js and include TypeScript-specific rules to ensure code quality.