sfdx-falcon-appx-demo-kit

Specialized project scaffolding for creating an AppExchange Demo Kit (ADK) Project using Salesforce DX and the SFDX-Falcon CLI Plugin

Usage no npm install needed!

<script type="module">
  import sfdxFalconAppxDemoKit from 'https://cdn.skypack.dev/sfdx-falcon-appx-demo-kit';
</script>

README

SFDX-Falcon: AppExchange Demo Kit (ADK)

The AppExchange Demo Kit (ADK) allows Salesforce Developers to build and share rich, dynamic demo orgs in a source-centric manner without requiring batch files or shell scripts!

AppExchange Demo Kit (ADK) falcon:adk:install

Anyone who has installed the Salesforce CLI and the SFDX-Falcon Plugin can install any ADK Demo with three simple commands.

$ sfdx falcon:adk:clone https://github.com/VivekMChawla/adk-sample.git

$ cd adk-sample

$ sfdx falcon:adk:install

Want to try for yourself? These instructions will help you install the SFDX-Falcon CLI Plugin, clone an AppExchange Demo Kit (ADK) starter project, and distribute your first ADK project to others.

Step One: Install Prerequisites

Before getting started, make your Salesforce, GitHub, and Local environments meet these prerequisites.

Once your environments meet all the prerequisites, following the rest of this guide should only take about 10 minutes.

Step Two: Install the SFDX-Falcon Plugin

The AppExchange Demo Kit (ADK) is installed as part of SFDX-Falcon, a plugin for the Salesforce CLI. Once you've completed the prerequisites from Step One, open a terminal (command prompt) and enter the following:

$ sfdx plugins:install sfdx-falcon

You should see something similar to this:

Install the CLI Plugin

Important Notes:

  1. The command sfdx plugins:install pulls the plugin source code directly from the sfdx-falcon package, hosted by NPM
  2. The SFDX-Falcon Plugin has not been digitially signed (yet), so you will need to acknowledge the warning to continue the installation

Step Three: Create an ADK-Projects Directory

Create a directory for your AppExchange Demo Kit (ADK) projects and change into the new directory.

$ cd ~
$ mkdir ADK-Projects
$ cd ADK-Projects

You should see something similar to this:

Create ADK-Projects Directory

Step Four: Create a Public GitHub Repository

Demos built with the AppExchange Demo Kit (ADK) are distributed via GitHub, so the first step when creating a new ADK project is creating a new, empty, public repository on GitHub.

Create a New Repository:

Create a New Repository

Important Notes:

  1. Go to https://github.com/new
    • Must be logged into GitHub first
  2. Choose a name for your ADK project
    • Only letters, numbers, hyphens, and underscores are allowed
    • Using all lowercase letters is strongly recommended
  3. Add a description for your ADK project
  4. Choose "Public" so your demo can be distributed to others
  5. Make sure that you do not initialize the repository with a README, add .gitignore, or add a license. The SFDX-Falcon plugin will create these for you.
  6. Click "Create Repository".

Copy the Git Remote URI (https only):

Copy the Git Remote URI

Important Notes:

  1. Click the "HTTPS" button
    • IMPORTANT: The ADK Setup Wizard does not support Git Remote URIs that use the SSH protocol, so you must copy the HTTPS version of your Git Remote URI
  2. The URL shown here is the Git Remote URI for your new repository
  3. Click the "copy to clipboard" button to automatically copy the Git Remote URI to your clipboard

Step Five: Create a New AppExchange Demo Kit (ADK) Project

Start the AppExchange Demo Kit project setup wizard by executing falcon:adk:create from the command line.

$ sfdx falcon:adk:create

You should see something similar to this: Run falcon:adk:create from the CLI

Important Notes:

  1. Run sfdx falcon:adk:create from the command line
  2. The SFDX-Falcon plugin will take 1-2 minutes to initialize the AppExchange Demo Kit project wizard
  3. Answer the questions presented to you by the wizard
    • IMPORTANT: For the question "What is the URI of your Git Remote?", paste the https URL you copied from GitHub in Step Three.
  4. Review the information you provided to the wizard
  5. Confirm that you want to create a new ADK project using these settings

Step Six: Run a Test Build

Change into the ADK project directory you just created, then run sfdx falcon:adk:install. Do so by entering the following:

$ cd uc-demo-app
$ sfdx falcon:adk:install

Step Six: Push Your ADK Project to GitHub

If you supplied a valid Git Remote URI during project creation, then your local repository already has a remote it can push to (origin).

$ git push origin master

Step Seven: Test Drive Cloning & Installing Your Demo

To see what others experience when consuming your demo, try the following:

$ cd ..
$ sfdx falcon:adk:clone https://github.com/MyGitHubUser/my-demo.git  test-drive

After entering the above, you will go through a breif interview to determien local settings for the project you're about to clone. Once this process is complete, enter the following:

$ cd test-drive
$ sfdx falcon:adk:install

To see the demo that you installed, open the org using the following:

$ sfdx force:org:open

Questions/Comments

To report bugs or request new features, create an issue for the SFDX-Falcon CLI Plugin which powers the AppExchange Demo Kit (ADK) and AppExchange Package Kit (APK).

Additional help is available to Salesforce ISV Partners by visiting the SFDX-Falcon Chatter Group in the Partner Community and posting questions there.

Acknowledgements

SFDX-Falcon, the SFDX-Falcon Plugin, and the AppExchange Demo Kit were created by Vivek M. Chawla LinkedIn | Twitter.

License

SFDX-Falcon and the AppExchange Demo Kit (ADK) are made available under the MIT License - see the LICENSE file for details.