Figma Plugin Manifest JSON: A Comprehensive Guide

by SLV Team 50 views
Figma Plugin Manifest JSON: A Comprehensive Guide

So, you're diving into the world of Figma plugin development? Awesome! One of the first things you'll encounter is the manifest.json file. Think of this file as the blueprint for your plugin. It tells Figma everything it needs to know about your plugin – what it does, how it's structured, and what permissions it needs. Let's break it down, piece by piece, so you can create a stellar plugin.

Understanding the Core Elements

The manifest.json file is essentially a JSON object containing key-value pairs that define your plugin. Here’s a rundown of the most important elements:

Name

The name field is pretty self-explanatory: it's the name of your plugin as it will appear in the Figma interface. Keep it short, sweet, and descriptive. This is what users will see when browsing for plugins, so make it count!

Example:

"name": "My Awesome Plugin"

ID

Every plugin needs a unique identifier, and that's where the id comes in. Figma automatically generates this ID when you publish your plugin. You don't need to define it in your manifest.json file initially, but it's crucial once your plugin is live.

API

The api field specifies the version of the Figma Plugin API your plugin is using. This ensures compatibility and access to the right features. Always use the latest version to take advantage of the newest functionalities and improvements.

Example:

"api": "1.0.0"

Main

This is where you tell Figma the entry point of your plugin's code. The main field points to the JavaScript file that will be executed when your plugin starts. This file usually contains the core logic of your plugin.

Example:

"main": "code.js"

UI

If your plugin has a user interface, the ui field specifies the HTML file that defines the UI. This allows your plugin to interact with users through custom panels and dialogs.

Example:

"ui": "index.html"

Editor Type

The editorType field indicates whether your plugin works in the Figma design editor or the FigJam whiteboard environment. It can be set to "figma", "figjam", or ["figma", "figjam"] if your plugin supports both.

Example:

"editorType": ["figma", "figjam"]

Diving Deeper: Advanced Features

Now that we've covered the basics, let's explore some of the more advanced features you can configure in your manifest.json file.

Widget API

The widgetApi field is specifically for Figma widgets. If you're developing a widget, this field specifies the API version for widgets.

Example:

"widgetApi": "1.0.0"

Parameters

The parameters field allows you to define input parameters for your plugin. These parameters can be accessed from the Figma UI and passed to your plugin's code.

Example:

"parameters": [
 {
 "name": "text",
 "key": "text",
 "type": "string",
 "description": "The text to display",
 "allowFreeform": true
 }
]

Parameter Only

Setting parameterOnly to true indicates that your plugin only accepts parameters and doesn't have a UI. This is useful for plugins that perform background tasks based on input parameters.

Example:

"parameterOnly": true

Menu and Contextual Menu

The menu field allows you to add your plugin to the Figma menu. You can define the menu item's name and the command it executes.

Example:

"menu": [
 {
 "name": "My Plugin Action",
 "command": "myAction"
 }
]

The contextualMenu field lets you add options to the right-click context menu in Figma, offering quick actions related to selected objects.

Command and Commands

A command is a specific action that your plugin can perform. The commands field is an array that lists all the commands your plugin supports.

Example:

"commands": [
 {
 "name": "Do Something",
 "id": "doSomething",
 "handler": "./src/doSomething.js"
 }
]

Onload, OnSelectionChange, OnViewportBoundsChange, and OnEdit

These are event handlers that allow your plugin to respond to specific events in Figma.

  • onload: Triggered when the plugin is loaded.
  • onSelectionChange: Triggered when the user's selection changes.
  • onViewportBoundsChange: Triggered when the viewport bounds change.
  • onEdit: Triggered when the document is edited.

Example:

"onload": {
 "handler": "./src/onload.js"
},
"onSelectionChange": {
 "handler": "./src/onSelectionChange.js"
}

OnMouseEnter and OnMouseLeave

These event handlers are triggered when the mouse pointer enters or leaves the plugin's UI.

Drop and Drop Types

The drop field allows your plugin to handle drag-and-drop events. You can specify the types of files or data that your plugin can accept.

Example:

"drop": {
 "types": ["image/png", "text/plain"],
 "handler": "./src/dropHandler.js"
}

Settings

The settings field allows you to define settings for your plugin. These settings can be accessed and modified by the user.

Example:

"settings": [
 {
 "name": "API Key",
 "key": "apiKey",
 "type": "string",
 "description": "Your API key for accessing external services"
 }
]

Permissions

The permissions field specifies the permissions that your plugin requires. This is crucial for security and ensures that your plugin can only access the resources it needs.

Example:

"permissions": [
 "network",
 "document"
]

Crafting a Robust manifest.json: Best Practices

Creating a well-structured manifest.json is essential for a smooth plugin development experience. Here are some best practices to keep in mind:

Keep it Clean and Organized

Use proper indentation and formatting to make your manifest.json file easy to read and understand. This will help you quickly identify and fix any issues.

Use Descriptive Names and Descriptions

Make sure your plugin's name and descriptions are clear and concise. This will help users understand what your plugin does and how it can benefit them.

Declare Only Necessary Permissions

Request only the permissions that your plugin actually needs. This will help build trust with users and ensure that your plugin is secure.

Test Thoroughly

Before publishing your plugin, test it thoroughly to ensure that it works as expected and doesn't cause any issues.

Stay Up-to-Date

Keep your manifest.json file up-to-date with the latest Figma Plugin API changes. This will ensure that your plugin remains compatible and takes advantage of the newest features.

Real-World Examples and Use Cases

To give you a better understanding of how these elements come together, let's look at some real-world examples and use cases.

Example 1: A Simple Text Transformation Plugin

Let's say you're creating a plugin that transforms selected text in Figma. Your manifest.json file might look like this:

{
 "name": "Text Transformer",
 "id": "unique-plugin-id",
 "api": "1.0.0",
 "main": "code.js",
 "ui": "index.html",
 "editorType": ["figma", "figjam"],
 "menu": [
 {
 "name": "Uppercase",
 "command": "uppercase"
 },
 {
 "name": "Lowercase",
 "command": "lowercase"
 }
 ],
 "commands": [
 {
 "name": "Uppercase",
 "id": "uppercase"
 },
 {
 "name": "Lowercase",
 "id": "lowercase"
 }
 ]
}

In this example, the plugin provides two menu options: