Salesforce CLI Plug-In Developer Guide
Total Page:16
File Type:pdf, Size:1020Kb
Salesforce CLI Plug-In Developer Guide Salesforce, Winter ’22 @salesforcedocs Last updated: July 21, 2021 © Copyright 2000–2021 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners. CONTENTS Salesforce CLI Plug-In Developer Guide . 1 Salesforce CLI Plug-Ins . 1 Salesforce CLI Architecture . 3 Get Started with Salesforce CLI Plug-In Generation . 5 Naming and Messages for Salesforce CLI Plug-Ins . 7 Customize Your Salesforce CLI Plug-In . 13 Test Your Salesforce CLI Plug-In . 32 Debug Your Salesforce CLI Plug-In . 33 Best Practices for Salesforce CLI Plug-In Development . 33 Resources for Salesforce CLI Plug-In Development . 35 SALESFORCE CLI PLUG-IN DEVELOPER GUIDE Discover how to develop your own plug-ins for Salesforce CLI. Explore the Salesforce CLI architecture. Learn how to generate a plug-in using Salesforce Plug-In Generator, use Salesforce’s libraries to add functionality to your plug-in, and debug issues. Learn about our suggested style guidelines for naming and messages and our recommended best practices for plug-ins. Salesforce CLI Plug-Ins A plug-in adds functionality to Salesforce CLI. Some plug-ins are provided by Salesforce and are installed by default when you install the CLI. Some plug-ins, built by Salesforce and others, you install. When you have a requirement that an existing plug-in doesn’t meet, you can build your own using Node.js. Salesforce CLI Architecture Before you get started with adding functionality to Salesforce CLI, let’s take a high-level look at how the CLI and its dependencies and plug-ins work together. Get Started with Salesforce CLI Plug-In Generation Set up your computer for Salesforce CLI plug-in generation, and then generate a plug-in. Naming and Messages for Salesforce CLI Plug-Ins Before you dive into coding, take some time to plan your naming strategy. And it’s never too early to start thinking about the messages you display for your users. Customize Your Salesforce CLI Plug-In To customize your plug-in, duplicate and update the generated files. You can customize your commands’ parameters, properties, error-handling, and output. Test Your Salesforce CLI Plug-In While you’re coding and customizing your plug-in, be sure to write associated tests for each new feature to ensure that it’s working as you expect. In your test suites, include both unit tests and more complex integration, smoke, and end-to-end tests. To help you with latter, we’ve created a library of testing utilities that you add to your environment as a Yarn developer dependency. Debug Your Salesforce CLI Plug-In We recommend using the Visual Studio Code (VS Code) editor, with Salesforce Extensions for VS Code, for your plug-in development. Included in the .vscode directory of Salesforce Plug-In Generator’s generated plug-ins is a launch.json config file. This config file allows you to attach a debugger to the Node process when running your commands. Best Practices for Salesforce CLI Plug-In Development We suggest that you follow these patterns when developing plug-ins for Salesforce CLI. Resources for Salesforce CLI Plug-In Development Bookmark these resources so that you can refer to them as you develop plug-ins. Salesforce CLI Plug-Ins A plug-in adds functionality to Salesforce CLI. Some plug-ins are provided by Salesforce and are installed by default when you install the CLI. Some plug-ins, built by Salesforce and others, you install. When you have a requirement that an existing plug-in doesn’t meet, you can build your own using Node.js. 1 Salesforce CLI Plug-In Developer Guide What Is a Salesforce CLI Plug-In? What Is a Salesforce CLI Plug-In? A plug-in adds commands or features to Salesforce CLI. For example, the aggregate salesforcedx plug-in provides the sfdx force commands. Salesforce CLI plug-ins are npm (Node.js package manager) packages. Node.js is a JavaScript runtime environment that supports execution outside of a browser. If you prefer strongly typed languages, don’t worry: We recommend that you use TypeScript, which transpiles to JavaScript. Salesforce Plug-In Generator’s sample plug-in uses TypeScript. Why Create a Salesforce CLI Plug-In? The Salesforce CLI core plug-ins provide commands and functionality to meet common needs that customers and partners have. But each team often has specific needs. That’s why Salesforce CLI is extensible. Even at Salesforce, different teams have different requirements. Salesforce teams create plug-ins, Salesforce employees create plug-ins as side projects, and Trailblazers in the Salesforce community create and share plug-ins. Knowledge and Skills for Salesforce CLI Plug-In Development Building a Salesforce CLI plug-in requires different knowledge and skills than most Salesforce development. Before you dive too deeply into plug-in development, familiarize yourself with these areas. What Is a Salesforce CLI Plug-In? A plug-in adds commands or features to Salesforce CLI. For example, the aggregate salesforcedx plug-in provides the sfdx force commands. Salesforce CLI plug-ins are npm (Node.js package manager) packages. Node.js is a JavaScript runtime environment that supports execution outside of a browser. If you prefer strongly typed languages, don’t worry: We recommend that you use TypeScript, which transpiles to JavaScript. Salesforce Plug-In Generator’s sample plug-in uses TypeScript. We recommend using TypeScript instead of JavaScript because it’s strongly typed and thus better suited to large projects. The stronger types give a better IDE experience and reduce common programming mistakes that are easy to make but hard to debug. A user installs a plug-in by running sfdx plugins:install PLUGINNAME , where PLUGINNAME is an npm package on npmjs.com. To see your installed plug-ins and their versions, run sfdx plugins. To see which versions of the default Salesforce-provided plug-ins are installed on your computer, run sfdx plugins --core. Why Create a Salesforce CLI Plug-In? The Salesforce CLI core plug-ins provide commands and functionality to meet common needs that customers and partners have. But each team often has specific needs. That’s why Salesforce CLI is extensible. Even at Salesforce, different teams have different requirements. Salesforce teams create plug-ins, Salesforce employees create plug-ins as side projects, and Trailblazers in the Salesforce community create and share plug-ins. Perhaps you have specific tools that you want to use for code analysis as part of your CI/CD automation process. You could build a plug-in that runs your bespoke code-analysis tool. Creating a plug-in provides the benefits of a consistent user experience and a common framework. One Trailblazer plug-in was developed by the Salesforce’s Tableau CRM team. The team knew that creating environments to develop, test, and share Tableau CRM apps, and converting those apps to templates for distribution, can be time-consuming. So they built the @salesforce/analytics plug-in to use scratch orgs to develop an app in Tableau CRM Analytics Studio. The plug-in imports data to datasets, builds dashboards, and connects everything. The team wrote commands that convert the app to templates and download the template JSON files for further refinement. Thanks to these commands, you can also quickly share the results of your work with other developers using a version control system. Your colleagues can push the template JSON files to their own scratch orgs for further testing and development. Because so much Salesforce functionality is surfaced in APIs, the sky’s the limit as to what you can build. With Salesforce Plug-In Generator, the @salesforce/core library, and the @salesforce/command package, you have the tools you need to get started with Salesforce CLI plug-in development. 2 Salesforce CLI Plug-In Developer Guide Knowledge and Skills for Salesforce CLI Plug-In Development Knowledge and Skills for Salesforce CLI Plug-In Development Building a Salesforce CLI plug-in requires different knowledge and skills than most Salesforce development. Before you dive too deeply into plug-in development, familiarize yourself with these areas. • TypeScript (or at least JavaScript, which TypeScript transpiles to) • Node.js • npm (Node.js Package Manager) • Yarn in modern JavaScript build tools • Salesforce APIs Salesforce CLI Architecture Before you get started with adding functionality to Salesforce CLI, let’s take a high-level look at how the CLI and its dependencies and plug-ins work together. Salesforce CLI Salesforce CLI is an npm package called sfdx-cli. You run it on your local machine or continuous integration (CI) system. It supports the installation of custom plug-ins. Most of the core functionality that Salesforce provides comes from plug-ins. salesforcedx Core Plug-Ins The sfdx force commands that you know and love are part of salesforcedx, an aggregate plug-in. @salesforce/core Package The @salesforce/core library provides client-side management of Salesforce DX projects, org authentication, connections to Salesforce APIs, and other utilities. Much of the core functionality that powers the salesforcedx plug-ins comes from this library. You can use this functionality in your plug-ins, too. @salesforce/command Package The @salesforce/command npm package provides the base command class for Salesforce CLI. Extend this class to give your commands access to common Salesforce CLI parameters, a logger, CLI output formatting, scratch orgs, Dev Hubs, and the user’s Salesforce DX project context. Open CLI Framework (oclif) oclif is an open-source CLI framework developed by Heroku. It powers Heroku CLI, parts of Salesforce CLI, the salesforcedx aggregate plug-in, and Salesforce Plug-In Generator.