Figma Plugin Manifest: Your JSON Guide

by Admin 39 views
Figma Plugin Manifest: Your JSON Guide

Alright, plugin developers! Let's dive into the heart of creating Figma plugins: the manifest.json file. This file is like the blueprint of your plugin, telling Figma everything it needs to know about your creation. Without a properly configured manifest, your plugin won't even show up in Figma. So, pay close attention, because we're about to break down every essential element! We'll make sure this comprehensive guide gets you up to speed. So buckle up, it's manifest time!

Understanding the Core Elements

The manifest file is written in JSON format, which stands for JavaScript Object Notation. It's a human-readable format used for transmitting data between a server and a web application. In our case, it's how your plugin tells Figma what it is and what it can do. So, let's go through all of the required aspects, guys.

name

Let's kick things off with the name field. This is arguably the most important field, as it's the name that users will see in the Figma interface. Keep it short, sweet, and descriptive.

Details to keep in mind:

  • Clarity: It needs to be clear enough for users to immediately understand what your plugin does.
  • Character Limit: It's advisable to keep it concise. Aim for under 30 characters to avoid truncation in the UI.
  • Uniqueness: Check the Figma Community to ensure your name isn't too similar to existing plugins. This will help avoid confusion.
"name": "My Awesome Plugin"

id

Next up, the id. This is a unique identifier for your plugin. Figma uses this id internally to keep track of your plugin. It should be a string. Generally, it's auto-generated when you create a new plugin in the Figma developer environment.

Details to keep in mind:

  • Uniqueness: The id must be globally unique across all Figma plugins. This is crucial to prevent conflicts.
  • Auto-generation: Usually, Figma generates this for you when you initially set up your plugin.
  • Immutability: Once your plugin is published, you cannot change this id. Doing so would essentially make it a new plugin.
"id": "123456789012345678"

api

The api field specifies the minimum Figma API version your plugin requires. This ensures that your plugin has access to the necessary features and functions within Figma. It's a best practice to keep this up-to-date so that your plugin can take advantage of the latest improvements Figma offers.

Details to keep in mind:

  • Versioning: Use semantic versioning (e.g., "1.0.0").
  • Compatibility: Ensure the API version you specify is compatible with the features your plugin uses.
  • Updates: Regularly check for new Figma API versions and update your plugin accordingly.
"api": "1.0.0"

main

The main field points to the main JavaScript file that contains your plugin's core logic. This is where the magic happens! When your plugin is run, Figma executes this file. The path should be relative to the manifest file.

Details to keep in mind:

  • Path: This should be a relative path to your main JavaScript file (e.g., code.js).
  • Entry Point: This file serves as the entry point for your plugin's functionality.
  • Bundling: If you're using a bundler like Webpack or Parcel, this should point to the bundled output file.
"main": "code.js"

ui

If your plugin has a user interface, the ui field specifies the HTML file that defines that UI. This HTML file can contain JavaScript and CSS to create interactive elements for your plugin. If your plugin runs solely in the background, without a UI, you can omit this field.

Details to keep in mind:

  • Path: This should be a relative path to your HTML file (e.g., ui.html).
  • UI Frameworks: You can use frameworks like React, Vue, or plain JavaScript to build your UI.
  • Communication: Use figma.ui API to communicate between the UI and the main plugin code.
"ui": "ui.html"

Diving Deeper: Optional Fields

Besides the core elements, there are several optional fields you can use to enhance your plugin and provide more information to Figma.

editorType

This field specifies whether your plugin works in Figma design files (design) or FigJam files (figjam). If your plugin works in both, you can specify mixed. If you leave it out, it defaults to design.

Details to keep in mind:

  • Compatibility: Ensure your plugin's functionality is appropriate for the specified editor type.
  • User Experience: Tailor the plugin's behavior to provide the best experience in either Figma or FigJam.
"editorType": ["design", "figjam"]

widgetApi and stylesheetApi

These fields are relevant if you're developing a widget rather than a plugin. widgetApi specifies the minimum API version for widgets, and stylesheetApi specifies the minimum API version for stylesheet-related features.

Details to keep in mind:

  • Widget Development: These are specifically for Figma widget development.
  • Versioning: Similar to the api field, use semantic versioning.
"widgetApi": "1.0.0",
"stylesheetApi": "1.0.0"

parameters

The parameters field allows you to define parameters that users can configure when running your plugin. These parameters can be of various types, such as text, number, boolean, or choice. This helps make your plugin more versatile and adaptable to different use cases.

Details to keep in mind:

  • Types: Support various types like string, number, boolean, and choice.
  • Configuration: Allow users to customize the plugin's behavior through parameters.
"parameters": [
 {
 "name": "Text",
 "key": "text",
 "type": "string",
 "description": "Enter the text to use",
 "allowFreeform": true
 }
]

parameterOnly

If your plugin consists solely of parameters and doesn't have a UI or any other code, you can set parameterOnly to true. This tells Figma that your plugin only needs to collect parameter values from the user.

Details to keep in mind:

  • Simplicity: Use this for simple plugins that only require parameter input.
  • No UI: If set to true, the plugin won't have a UI.
"parameterOnly": true

capabilitySet

The capabilitySet field declares what operations the plugin can do with the files. This allows more fine-grained control of plugin security and functionality.

Details to keep in mind:

  • Fine-Grained Control: Allows you to specify exactly what the plugin can do.
  • Security: Helps maintain a secure environment by limiting plugin capabilities.
"capabilitySet": {
 "allowUIMessage": true,
 "allowPluginCommand": true
}

menu

The menu field allows you to add custom menu items to the Figma interface, providing users with quick access to your plugin's features. You can create submenus and nest items to organize your plugin's functionality.

Details to keep in mind:

  • Customization: Add custom menu items to the Figma interface.
  • Organization: Create submenus and nest items for better organization.
"menu": [
 {
 "name": "My Plugin",
 "items": [
 {
 "name": "Do Something",
 "command": "doSomething"
 }
 ]
}
]

contextualMenuItems

Contextual menu items appear when a user right-clicks on a node in Figma. You can add custom items here to provide node-specific actions.

Details to keep in mind:

  • Context-Specific Actions: Add actions that are relevant to the selected node.
  • Improved Workflow: Streamline user workflows with quick access to common tasks.
"contextualMenuItems": [
 {
 "name": "My Custom Action",
 "command": "customAction"
}
]

commandId and commands

The commandId and commands fields are related to how your plugin executes specific actions. The commands array lets you define multiple commands that your plugin can perform, while commandId specifies the default command that's executed when the plugin is run without any specific command.

Details to keep in mind:

  • Multiple Actions: Define multiple commands for different actions.
  • Default Action: Specify a default command to execute when the plugin is run without a specific command.
"commands": [
 {
 "name": "Do Something",
 "id": "doSomething"
 },
 {
 "name": "Do Another Thing",
 "id": "doAnotherThing"
}
]

transformNodes

The transformNodes property is used to allow the plugin to modify the vector network of a shape or boolean operation. It is a crucial feature for plugins that need to perform complex manipulations of vector data directly.

Details to keep in mind:

  • Enable Vector Transformations: This setting enables the plugin to make changes directly to the vector points.
  • Necessary for Complex Edits: If your plugin requires deep modifications to vector data, this is the setting to use.
"transformNodes": true

Event Handlers: Reacting to Figma Events

Figma plugins can respond to various events within the Figma environment, allowing your plugin to react dynamically to user actions and changes in the document.

onLoad, onSelectionChange, onEdit, etc.

These fields define event handlers that are triggered when specific events occur in Figma. For example, onLoad is called when the plugin is loaded, onSelectionChange is called when the user changes their selection, and so on.

Details to keep in mind:

  • Dynamic Behavior: Allows your plugin to react dynamically to events.
  • Event-Driven: Enables event-driven programming within your plugin.
"onLoad": {
 "command": "onPluginLoad"
},
"onSelectionChange": {
 "command": "onSelectionChanged"
}

onMouseEnter, onMouseLeave, onViewportBoundsChange, onZoomChange, onResize, onDrop

These event handlers provide more specialized responses to different kinds of user interactions and document state changes.

Details to keep in mind:

  • Interactivity: Enhance the interactivity of your plugin by responding to user actions like mouse movements and drops.
  • Responsiveness: Make your plugin more responsive to changes in viewport bounds, zoom levels, and document resizing.
"onMouseEnter": {
 "command": "onMouseEnterHandler"
},
"onDrop": {
 "command": "onDropHandler"
}

Miscellaneous Fields

Finally, let's cover some additional fields that provide supplementary information about your plugin.

codeSandboxId

If your plugin is showcased on CodeSandbox, you can specify the CodeSandbox id here. This allows users to quickly access and explore your plugin's code.

Details to keep in mind:

  • Showcase: Link to your plugin's CodeSandbox for easy access to the code.
  • Community: Helps other developers understand and learn from your plugin.
"codeSandboxId": "your-codesandbox-id"

enableProposedApi

This boolean field indicates whether your plugin uses any proposed (experimental) Figma APIs. Use this with caution, as proposed APIs may change or be removed in future versions of Figma.

Details to keep in mind:

  • Experimental APIs: Indicates the use of experimental Figma APIs.
  • Volatility: Proposed APIs may change or be removed in future versions.
"enableProposedApi": true

documentationUrl

Provide a URL to your plugin's documentation. This helps users understand how to use your plugin effectively.

Details to keep in mind:

  • User Guidance: Link to comprehensive documentation for your plugin.
  • Support: Helps users understand how to use your plugin and troubleshoot issues.
"documentationUrl": "https://your-plugin-docs.com"

description

A brief description of your plugin. This is displayed in the Figma Plugin Marketplace. Keep it concise and informative.

Details to keep in mind:

  • Concise: Keep the description brief and to the point.
  • Informative: Highlight the key features and benefits of your plugin.
"description": "An awesome plugin that does amazing things."

version and versionName

The version field specifies the plugin's version number (e.g., "1.0.0"), while versionName provides a human-readable version name (e.g., "Initial Release").

Details to keep in mind:

  • Versioning: Use semantic versioning for the version field.
  • Readability: Provide a human-readable version name for clarity.
"version": "1.0.0",
"versionName": "Initial Release"

isSingleExecution

If set to true, this field indicates that your plugin can only run one instance at a time. This can be useful for plugins that manage global state or resources.

Details to keep in mind:

  • Single Instance: Ensures only one instance of the plugin runs at a time.
  • Resource Management: Useful for plugins that manage global state or resources.
"isSingleExecution": true

networkAccess

The networkAccess field specifies whether your plugin needs to access the internet. If set to true, your plugin can make network requests. Be mindful of user privacy and security when requesting network access.

Details to keep in mind:

  • Internet Access: Indicates whether the plugin needs to access the internet.
  • Security: Be mindful of user privacy and security when requesting network access.
"networkAccess": {
 "allowedDomains": ["example.com"]
}

permissions and allowedDomains

These fields are related to network access. permissions allows you to specify which network resources your plugin can access, and allowedDomains lists the domains that your plugin is allowed to communicate with.

Details to keep in mind:

  • Security: Limit network access to only the necessary resources and domains.
  • User Privacy: Be transparent about how your plugin uses network resources.
"permissions": ["https://api.example.com/*"],
"allowedDomains": ["example.com"]

muted

If set to true, the plugin's UI will be muted, preventing it from stealing focus or interrupting user workflows.

Details to keep in mind:

  • Non-Intrusive: Great for plugins that run in the background or don't require immediate user interaction.
  • Improved User Experience: Helps maintain a smooth workflow without unexpected interruptions.
"muted": true

Conclusion

The manifest.json file is the cornerstone of your Figma plugin. Mastering its various fields and options will enable you to create powerful, user-friendly plugins that enhance the Figma experience. By understanding each field, you can create plugins that are not only functional but also integrate seamlessly with Figma's environment. So, go forth and manifest your plugin ideas into reality! You've got this, guys! Remember to always refer to the official Figma plugin documentation for the most up-to-date information. Happy coding!