Creating Extensions
Nova supports a flexible extension API for adding a wide variety of features to Nova, including new syntaxes, themes, language servers, Task Templates, validators, integrations with external tools, and more.
Looking for Nova’s API documentation? You’ll find it at docs.nova.app.
Creating a New Extension
To get started on developing a Nova extension, first head to Nova’s Settings > General and enable Show extension development items in the Extensions Menu. This adds some additional menu items to the Extensions menu for creating, testing, and submitting Extensions. You’ll also need to create and sign into an extension developer account.
Once you’re all set up, simply head to Extensions > Create New Extension… to create a new extension.
Types of Extensions
Your first decision will be what type of Extension you want to create. Nova includes a number of templates to help kickstart different kinds of Extensions:
-
Action Extension: Adds general-purpose commands or menu items to Nova.
-
Clips: Adds pre-made Clips to Nova.
-
Completions Provider: Suggests completions for use in the Editor.
-
Editor Extension: Acts on text in the Editor, such as formatting.
-
Issues Provider: Reports issues and warnings found in the Editor.
-
Key Bindings: Provides pre-made key binding sets.
-
Language Definition: Defines a new syntax mode for the Editor.
-
Language Server Extension: Connects to a language server for enhanced editing functionality.
-
Sidebar: Adds a new sidebar to Nova’s interface.
-
Task Provider: Automatically provides Tasks the user can run based on project context.
-
Task Template: Provides pre-defined Task Templates users can configure.
-
Theme: Provides new window or editor themes for Nova, primarily written in CSS.
These choices aren’t set in stone, just presets to help you quickly get started on common kinds of extensions. An extension can provide multiple features to Nova that overlap with several of these extension types. You can also choose to create a blank extension that doesn’t include any template files beyond the bare essentials.
Initial Configuration
Once you choose an extension type, you’ll need to provide some identifying information about your extension. Depending on the type of extension you chose, you may also need to enable particular entitlements.
- Extension Name
- The display name for your extension.
- Organization
- Your Nova developer account can possess multiple organizations
- Extension Identifier
- A unique identifier for this extension, appended to the identifier for your organization selected above. Helps distinguish your extension from others with similar names.
Entitlements
Entitlements give your extension permission to use certain Nova APIs that may enable access to users’ personal data. Any entitlements your extension requires will be listed on its Extension Library page to inform users that your extension may access this data.
- Clipboard
- Allows your extension to read or modify the content’s of the user’s clipboard, for features like taking action on copied or pasted text.
- File System
- Allows your extension to directly read or modify files and directories on the user’s Mac.
- Network
- Allows your extension to make arbitrary HTTP requests over the network.
- Processes
- Allows your extension to launch and communicate with external processes on the user’s Mac.
Writing Your Extension
Once you’ve completed the initial creation process, your extension will be saved within a newly-created .novaextension bundle. This bundle will hold all the source files and resources for your extension, and will be automatically added to Nova as a Local Project.
First, you’ll likely want to open extension.json and add some additional metadata about your extension. The name, identifier, and organization fields will automatically be filled out for you, but you’ll also want to write a custom description for your extension. Extensions submitted to the Extension Library also require a bugs value that provides a URL where users can submit bug reports.
Nova Extensions are primarily written in JavaScript, using Nova’s feature-packed JavaScript API. Themes are primarily written in CSS. For adding new syntax modes to Nova, you can compile Tree-sitter parsers to bundle in your extension.
For detailed documentation of Nova’s extension API, check out the Nova Extension API library at docs.nova.app.
Testing Your Extension
Once you’re ready to start testing your extension, head to the Extensions menu > Activate Project as Extension. This will temporarily add your Nova Project to Nova as an extension for testing. You can remove your in-development extension at any time from the Extensions menu > Deactivate Project as Extension.
Syntax Inspector
The Syntax Inspector provides insight into how Nova is parsing and highlighting a document in the Editor, which can be invaluable for developing certain extensions such as new syntaxes or themes. It can be enabled from the Editor menu > Syntax Inspector, or by clicking the
icon in the Editor’s Status View.
While the Syntax Inspector is enabled, you can hover over any symbol, word, or character in Nova’s Editor to see both how the current syntax mode is parsing that token, and what CSS selectors the current theme is applying to that token. This can be useful in debugging issues where a document is not being parsed correctly by a syntax extension, or a theme is not being applied as expected.
Extension Console
From the Debug Pane, you can access the Extension Console. The Extension Console will show any errors and warnings thrown by your extension’s code while executing, as well as any manual console output you print to it.
Each entry displays the time the message was logged, the extension that logged the message, and the message itself. You can filter the console by extension by selecting a source from the menu in the top-left. In the top-right, you can filter the view by errors, warnings, or logs. You can also clear the console if needed.
Distributing Your Extension
Once your extension is ready to go, you’ll probably want to distribute it to other users! One option is to just distribute the .novaextension bundle any way you wish. Users can simply double-click that bundle to install the extension in Nova. Of course, you can also submit your extension to the Nova Extension Library to make it easily discoverable to any Nova user.
To get started, open your extension as a Project, then go to the Extensions menu > Submit to the Extension Library…. First, Nova will check to ensure you’ve included any necessary metadata for your extension, such as an icon and bug reports link. If any required metadata is missing, you won’t be able to submit the extension until you provide it.
If everything checks out, Nova will allow you to submit your extension.
Once submitted, the Extension Library will create a listing for your extension using the metadata provided in extension.json, and other Nova users can download your extension for themselves. You can manage your submitted extensions by signing into your extension developer account.
Using the Nova CLI
The Nova CLI tool provides some additional commands just for extension developers, to help automate testing and distributing your extensions. All of the following extension development commands are invoked using nova extension <subcommand>. You can also run nova help extension <subcommand> to view documentation for each command.
Subcommands
activate- Activate a .novaextension bundle as an extension in Nova. Example:
nova extension activate /path/to/bundle.novaextension invoke- Invoke an extension command in an existing Nova workspace. This allows you to automate extension actions from command line scripts. The command must be registered by an extension using the CommandsRegistry API.
login- Log in to your Nova extension developer account from the command line. You will be prompted to enter your credentials to log in.
logout- Log out of your current Nova extension developer account.
publish- Submit an extension bundle to the Extension Library. Example:
nova extension publish /path/to/bundle.novaextension validate- Check an extension bundle for any issues or warnings that may prevent submission to the Extension Library. Example:
nova extension validate /path/to/bundle.novaextension whoami- Print the email address for the Nova extension developer account currently signed in.
|
← Previous The Extension Library |