Open Sourcing the Core Extension

In a prior article, I wrote about how the Adobe Experience Platform Launch team ❤️ open source. We strongly believe that open source matters to the community for three reasons: transparency, ease of implementation, and continuous improvement. In an effort to continue our open sourcing efforts, we’re happy to announce that we’ve open sourced the Core extension (see the code repository).

What is the Core extension?

Adobe Launch allows companies to deploy marketing technologies onto their websites. As part of the process, marketers build rules to define how marketing technologies react to events that happen while a user is on their website. As an example, a marketer may create a rule that behaves as follows: Once a user has remained on the website for longer than three minutes with an item in the shopping cart, show a 10% discount offer.

While Adobe Launch provides the ability to create rules, the building blocks that make up rules (event types, condition types, action types, and data element types) do not come from Launch itself. Instead, Launch acts as a platform while extensions provide these important building blocks. Launch users can install whichever extensions they would like and use the building blocks the extensions provide to build rules. In some ways, this is similar to using an app store on your phone to install applications you would like to use.

We understood there are fundamental building blocks that apply to most marketers. For example, building a rule based on when a user clicks an element on a web page is very common. Building a rule based on whether a user is on a particular page is also very common. To provide these very common building blocks, and in an effort to “eat our own dog food”, the Adobe Launch team created the Core extension. The Core extension is automatically installed by default on every property created in Adobe Launch, but can also be uninstalled like any other extension.

Open sourcing challenges

We knew from day one that we wanted to open source the Core extension. We wanted it and our customers wanted it. As it turns out, open sourcing a project when it relies on other projects that are not open sourced can be a challenge.

In the case of the Core extension, its user interface leverages a UI component library called react-spectrum. React-spectrum is a component library built by Adobe and provides the consistent look and feel customers find across Adobe products. Unfortunately, it has not yet been open sourced, and it is distributed within Adobe through an internal npm repository.

An npm repository is a collection of primarily JavaScript-based software projects that can be downloaded and used within other software projects.

In order for external developers to be able to run and test the Core extension locally, they also need react-spectrum code. To accomplish this, we needed to address problems in three different areas: product, legal, and technical.

Product

We first needed to align internally about the future of react-spectrum and its relationship to the Core extension. Would react-spectrum be open sourced and, if so, when? If it wasn’t going to be open sourced soon, then we needed to decide whether to include the react-spectrum code directly inside the Core extension repository in some way or use an entirely different UI library. Ultimately, we decided to continue using react-spectrum and include its code directly inside the Core extension.

While react-spectrum is not yet open sourced, Spectrum CSS is. Spectrum CSS provides the Adobe style for many UI components, which is typically sufficient for simple form elements like textfields and checkboxes, while react-spectrum provides the JavaScript logic for more complex UI components like datepickers and dropdowns.

Legal

We desired to release the Core extension under the Apache 2.0 license, which is the standard for most projects open sourced by Adobe and is quite permissive. React-spectrum, however, was not using such a license. In order to distribute react-spectrum with the Core extension’s source code, we needed to make it clear to external developers that react-spectrum was not governed by the Apache 2.0 license. This required coordination with legal counsel and resulted in adding the following header to all react-spectrum files that are shipped with the Core extension:

/**
 * Use of this code is governed by the Adobe Terms of Use and
 * Adobe Developer Additional Terms, and the license attached
 * to this repo does not apply.
 */

Technical

The first step a developer takes before working on the Core extension project is to run the command npm install. This process is very common when developing web libraries and apps, which uses the npm package manager to install dependency packages from a shared npm repository. Most of the dependencies for the Core extension are pulled from the public npm repository that many JavaScript developers are familiar with. However, react-spectrum is not distributed on the public npm repository, but instead is distributed through a private npm repository within Adobe. This means if an external developer would run npm install within the Core extension project, the process would fail, because the external developer’s computer would not be able to access Adobe’s internal npm repository.

In order to solve this problem, we decided to download the react-spectrum package as a tarball (a group of files bundled together into a single file) from the internal npm repository, unpackage the tar file, prepend the requisite legal headers to each of the source files as described above, repackage the files into a tarball, then commit the tarball file to the Core extension’s repository.

An npm command exists for downloading a tarball for a particular npm package. For example, if you would like to download the tarball for the npm package named left-pad, you can run the following command within a terminal: npm pack left-pad. A file named left-pad-1.3.0.tgz containing the package’s contents will be added to your current working directory.

When running npm install, npm dependencies are typically installed from a remote npm repository, but they can also be installed from local tarballs. In order to install react-spectrum from the tarball we had prepared for distribution, we needed to change the dependency entry in our package.json file from this:

”@react/react-spectrum”: “2.25.0”

to this:

”@react/react-spectrum”: “file:react-react-spectrum-2.25.0.tgz”

By doing so, the npm package manager would automatically use the tarball when installing the react-spectrum dependency.

This was simple enough, but there was another catch. React-spectrum depended on a separate package called collection-view, which was also distributed only through Adobe’s private npm repository. Similar to what was done with react-spectrum, we also prepared a tarball for collection-view. Unfortunately, while you can configure package.json to indicate to the npm package manager that a dependency should be installed from a tarball, you cannot configure it to tell the npm package manager that a dependency’s dependency should be installed from a tarball.

To solve this problem, we decided to switch from the npm package manager to the Yarn package manager for installing dependencies. Yarn supports selective dependency resolutions natively, which successfully allows us to configure package.json in such a way that Yarn will install the collection-view dependency from the tarball. Now the first step for a developer working on the Core extension is yarn install rather than npm install.

Yarn still allows projects to install dependencies from npm repositories, even though Yarn does not carry the “npm” name.

Moving forward

Now that the Core extension has been open sourced, we hope it helps you in your Launch implementations. Maybe it will help you better understand how the Core extension operates. Perhaps you’ll feel like contributing bug fixes or new functionality (Jan Exner has already submitted the first pull request!). Whatever the case, we’ll continue seeking appropriate opportunities to open source our software.