Getting Started with Project Firefly
Project Firefly is a framework that allows developers to build & deploy serverless applications that run within the Adobe Experience Cloud. Firefly supports both Headless and Single Page Applications.
Note: In order to get started with Firefly, your organization will need to register for the Developer Preview program. The remainder of this post will assume you have access.
Headless Applications are created using NodeJS with Adobe I/O Runtime (Adobe's Serverless platform). These headless applications are perfect for a variety of use cases including:
- Service Integrations
Single Page Applications
Single Page Applications (SPAs) provide a user interface to Headless Applications. Firefly SPAs are created using React Spectrum which is a ReactJS implementation of Adobe’s Spectrum design system.
The quickest way to generate a Firefly application is by using the AIO CLI Tool.
AIO CLI Tool
The Adobe I/O Extensible CLI tool provides a common command-line interface for working with Firefly applications. You will need to install NodeJS (version 12) and NPM.
Tip: It's easy to manage multiple versions of NodeJS on a single machine with the help of NVM.
After NodeJS and NPM are installed, open the terminal application and run the following commands.
1) Install the AIO CLI tool using NPM
npm install -g @adobe/aio-cli
2) Verify the AIO CLI tool installed successfully
3) Make sure all plugins are up to date
Creating the Firefly Application
Using the terminal, navigate to your project folder and initialize the Firefly application with the following command:
aio app init
The application creation wizard will lead you step-by-step through the process of defining your organization, project name & workspace, as well as selecting the features you want to initialize your application with.
The code project will be generated based on the preferences you specify, while completing the creation wizard.
To see your application in action, return to the terminal and run one more command:
aio app run
Open your web browser and enter http://localhost:9080 into the address bar. You are officially up and running on Firefly.
In addition to the AIO CLI tool, you will use the Developer Console to manage your project, add and authorize APIs, as well as gain helpful insights.
In this section, we will use the Developer Console to add an API and credential to our project. Before we do, it's worthwhile to note some of the differences between using the AIO CLI tool and the Developer Console when creating projects.
The Developer Console is available at http://console.adobe.io. Using the Developer Console, it's possible to create a new Empty Project or a new Project from Template.
From the Home page quick start menu, you have the option to create a new empty project. When an empty project is created, there are two things to be aware of:
- The project name is generated automatically for you
- Adobe I/O Runtime and workspaces need to be manually enabled and added to the project
The project name is used to define the Adobe I/O Runtime Namespace which we will soon see. It is always possible to edit the title of a project, the name of the project cannot be modified after creation.
The Create New Project button on the Project page allows you to create a new project from a template.
When the Project Firefly template is used, the project name can be specified during setup. The Adobe I/O Runtime is enabled by default. Production and Stage workspace are also added to the project by default in the same way as when using the AIO CLI tool.
Add an API
Now that we have reviewed the Developer Console and understood the options and implications of how a project is created, we can add an API and credential to the project.
1) Navigate to the Projects page and locate the project you created using the AIO CLI tool earlier.
2) Select a workspace and click the Add Service button and select API from the drop-down menu.
3) Select the Experience Cloud category and then select the Cloud Manager API.
4) For the final step we will generate a credential (JWT) and configure the API. Click Next to continue.
5) Click Generate Keypair. Download and save the credential to your project folder.
6) Click Next to continue. Configuration options will vary depending on the API added to the project. For the Cloud Manager API, you will select the product profiles that should be associated with the credential and then save the configuration.
7) Return to your project workspace page and click the Download All button. This will generate a JSON representation of the project configuration. Save this to your project folder on your filesystem. We will use this to update our project code in the next and final step.
8) Open the terminal application and navigate to your project folder, then run the following command
aio app use <project-configuration-filename>
The above command will tell Firefly to read the JSON configuration file downloaded in the previous step. Agree when prompted to overwrite the local .env and .aio files. This will bring your code project in sync with the project changes made within the Developer Console.
In this post, we reviewed what Project Firefly is and the technologies behind it. We also gained familiarity with the resources and tools that are used when working on Firefly projects like AIO CLI and Developer Console.
Now that the stage is set, in future posts, I will begin sharing Project Firefly solutions to address common use cases.