Get Ready to Create Your First Unlocked Package

Get Ready to Create Your First Unlocked Package

Salesforce Developer Experience (DX) provides a new set of tools and processes to streamline the development life cycle for Salesforce developers. These new tools focus on team development and automation, and the notion of modular, package-based development. Modular development is a game changer for both customers and ISVs.

In this quick start, we introduce you to Unlocked Packages as a mechanism for managing change to the internal business apps you build. If you’re looking for a deep dive into unlocked packages, look at the Unlocked Packages for Customers module.

What Is an Unlocked Package?

If you’re new to packaging, you can think about a package as a container that you fill with metadata. It contains a set of related features, customizations, and schema. Salesforce offers several types of packages, each with unique characteristics. For now, you’re going to work with a special package type, an Unlocked Package, which is especially suited for internal business apps.

Unlocked packages help you add, edit, and remove metadata in your org in a trackable way. You can apply your source and metadata to multiple orgs, and upgrade your Salesforce apps easier and faster. Packages encapsulate all the metadata changes and updates you plan to make.

With an unlocked package, you have a lot of flexibility. Your admins can make changes directly in production in response to emergency change requests because metadata in unlocked packages can be modified in a production org. At the same time, this flexibility comes with responsibility. Ensure that you have the proper governance in place to prevent cases where package updates overwrite changes that admins make directly in production. This use case is covered in more depth in the Unlocked Packages for Customers module.

How Does Salesforce DX Help?

To build your first unlocked package, you use all tools and techniques you’ve learned from previous modules in the Get Started with Salesforce DX trail.

Once you set these things up you’re ready to move ahead.

Configure Your Environment

Once you answer “yes” to all these questions, you’re good to go.

Get Your Trailhead Playground Credentials

After you build your unlocked package, you test it in a scratch org. Eventually, you install it in one of your more permanent orgs, like a sandbox. During this quick start, we use your Trailhead Playground (TP) as the target org.

To complete the quick start, ensure that you know the password to your TP so you can log in from the Salesforce CLI. Head over to Find the Username and Password for Your Trailhead Playground for more information on how to get your TP username and password.

Once you have your credentials, log in to your TP using the Salesforce CLI. Be sure to give the TP an alias to make your life easier later in the quick start.

sfdx force:auth:web:login --setalias MyTP

Run sfdx force:org:list to confirm that your TP credentials are stored locally.

=== Orgs
     ALIAS       USERNAME                         ORG ID              CONNECTED STATUS
───  ──────────  ───────────────────────────────  ──────────────────  ────────────────
(D)  DevHub      myDevHub@example.com             00DB0000000Ige5MAC  Connected
     MyTP        myName@cunning-bear-311000.com   00D6A000000fH8CUAU  Connected
     TestingOrg  name@example.com                 00DB0000000Im58MAC  Connected

ALIAS     SCRATCH ORG NAME  USERNAME             ORG ID              EXPIRATION  DATE
────────  ────────────────  ───────────────────  ──────────────────  ────────────────
Scratch1  myAcme            test@example.com     00DZ000000N8ItoMAF  2018-03-01

Now, whenever you run a command from the Salesforce CLI and use -u MyTP, it performs the operation against your TP.

Download the Sample App from GitHub

To demonstrate the power of unlocked packages, we’re going to use a sample app that intrinsically highlights the value of the Lightning Platform. It’s fast, it’s fun, and it empowers you to search for and post your favorite animated GIFs to Chatter. That’s right, meet GIFter, the GIF-to-Chatter app that you didn’t know that you needed.

The app is available for you to use in GitHub: https://github.com/forcedotcom/GIFter

To get started, clone the repository to create your own version of the app to use and modify independent of the sample.

  1. Open a new Terminal (Mac) or Command Prompt (Windows) window, then create a unique directory to do your work in:
    mkdir my_gifter_project
    cd my_gifter_project
  2. On the command line, clone the app repository.
    git clone https://github.com/forcedotcom/GIFter.git
  3. Make sure that your project scratch definition file follows this format. You can find the scratch org definition in config/project-scratch-def.json.
    {
        "orgName": "GIFter",
        "edition": "Developer",
        "settings": {
            "orgPreferenceSettings": {
                "s1DesktopEnabled": true,
                "chatterEnabled": true,
                "s1EncryptedStoragePref2": false
            }
        }
    }
  4. Open the directory.
    cd GIFter
Note

Note

If this time is your first using a GitHub repository or you need a refresh on these concepts, look at the Git and GitHub Basics Trailhead Module or review the GitHub Help articles.

You now have the app. Let’s unlock an infinite selection of animated GIFs!

Create a GIPHY App

I know you’re excited to start searching for animated GIFs and post them to Chatter. Who isn’t? But, for this project to work, you first create a GIPHY app and get yourself an API Key.

  1. Head over to https://developers.giphy.com/.

    After you create and log in to your account, you see your Dashboard. This app acts as the liaison between our app and the GIPHY API.

  2. Click Create an App.
  3. Give the new app an App Name and App Description, then click Create New App.

    You can choose whatever you want, but we recommend “GIFter” as it’s always good to keep it related to the intended function.

    Create a New App dialog where you enter your app name (example shows gifter) and an app description (example shows "My animated GIF to Chatter app")
  4. Copy the displayed Api Key, so you can use it in the next step.
  5. In the GIFter app you cloned earlier, let’s update the code to use your GIPHY API key.

    Open the file force-app/main/default/staticresources/GIPHY.resource using your favorite IDE or text editor. Did you know that we have amazing extensions for Visual Studio Code? Grab the Salesforce Extensions for VS Code from the Visual Studio Marketplace.

    In the file GIPHY.resource (which is a JavaScript file shared by the Lightning components in the app) see the following line of code.

    var apiKey = "YOUR_GIPHY_API_KEY";

    Update YOUR_GIPHY_API_KEY to use your Api Key.

  6. Save the GIPHY.resource file.
Important

Important

Your API key is a secret! Do not commit your API key to a public GitHub repository. While it’s beyond the scope of this quick start, there are many ways for you to securely keep track of secrets. For now, don’t check it in!

All the prework is done. Great job! Now let’s go post some animated GIFs to Chatter.

We won't check any of your setup. Click Verify Step to go to the next step in the project.

retargeting