creating-an-extension.md

description
Create a new extension project and become familiar with its structure.

Creating an Extension

System Requirements

Before creating an extension make sure the following requirements are met.

• You have Node.js 16.10 or higher installed.
• You have Git installed.

Starting a New Extension

CodeEdit makes it easy to create a new extension project using the Extensions menu. To get started choose Extensions > New Extension…, which will open a Save dialog prompting you to select a location for your project.

{% hint style="info" %} Extension Developer Account

It is not necessary to have a CodeEdit developers account if you have no intention of offering the extension on the Extension Store. However, an account is required to publish an extension and make it publicly available. See Publishing an Extension for more information. {% endhint %}

File and Folder Structure

Every extension project is created with the default file and folder structure shown below.

.
├── assets/
│   └── icon.png
├── node_modules/
│   └── ... 
├── src/
│   └── index.js
├── .gitignore
├── CHANGELOG.md
├── package.json
├── package-lock.json
└── README.md

• assets/ contains all images used by the extension, which will be bundled with the extension and accessible at runtime. Every extension should also include an icon.png file to be displayed in the CodeEdit UI and extension store.
• node_modules/ contains the project dependencies. Its contents should not be manually altered. Instead, to add a dependency use package.json and npm.
• src/ contains the project source files in JavaScript (.js, .jsx) or TypeScript (.ts, .tsx) format.
• src/index.js serves as the main entrypoint for the extension. See the index.js section below to learn more.
• .gitignore includes a list of files and folders to be ignored by Git version control. See the Git documentation for more information.
• CHANGELOG.md includes information about changes made in each version of the extension. This file should be written in Markdown and will be displayed in the extension store alongside details included in README.md when the extension is published.
• package.json is a manifest file that with metadata about the extension. It is also used to add extension dependencies. See the package.json section below to learn more.
• package-lock.json is a file generated by npm containing detailed information about the dependencies used, such as the exact version of a package that is installed. Do not manually alter this file

package.json

The package.json extension manifest file is a superset of the npm package.json file so only a single file is required to configure your extension. Please refer to the npm documentation for more information.

{
  "name": "my-extension",
  "displayName": "My Extension",
  "author": "johnnyappleseed",
  "version": "1.0.0",
  "license": "MIT",
  "keywords": ["codeedit", "extension"],
  "engines": {
    "codeedit": ">=1.1.0",
    "node": "12.x",
    "npm": ">=6.4"
  },
  "main": "src/index.js",
  "activation": "src/activate.js",
  "deactivation": "src/deactivate.js",
  "commands": [
    {
      "name": "share-code-screenshot",
      "title": "Share Code Screenshot",
      "description": "A command to share a screenshot of the selected code",
      "mode": "sheet"
    }
  ],
  "dependencies": { ... },
  "devDependencies": { ... }
}

Properties

Property	Required	Description
name	Yes	The extension identifier.
displayName	Yes	Human readable extension name.
description	Yes	A single sentence describing the extension.
icon	Yes	An icon for the extension. See our icon specifications.
author	Yes	The username of who built the extension.
categories	Yes	The categories that apply to this extension. See a list of our extension categories.
commands	Yes	An array of commands that are offered by this extension. See Command Properties.
contributors	No	A list of usernames of contributors of this extension.
keywords	No	Keywords that apply to this extension.
preferences	No	An array of preferences that are offered by this extension. See Preferences Properties.

index.js

The index.js file serves as the main entrypoint for the extension. It should export two methods, activate and deactivate. The activate method is called only once when the Activation Event specified in extension.json has occurred.

import * as codeedit from 'codeedit';

// Method is called once when the extension is first activated.
export function activate() {
  // Instantiate extension object.
  let myCompletionProvider = new myCompletionProvider();
  
  // Register the extension object.
  codeedit.extensions.registerCompletionProvider(myCompletionProvider);
}

export function deactivate() {
  // Add any code that should be run when the extension stops running.
}