Apex Recipes

Introduction

Apex Recipes is a library of concise, meaningful examples of code for common use cases utilizing best practices. They reflect enterprise patterns that can be utilized for real world solutions and should be relevant to developers of all skill levels. The code is intended to reflect clarity while trying to maintain brevity. See the Table of Contents for installation options. We recommend using the Salesforce CLI and a scratch org for your initial deployment.

Learn more about this app by completing the Quick Start: Explore the Apex Recipes Sample App Trailhead project or by watching this short presentation video.

Table of contents

• Installing Apex Recipes Using a Scratch Org: This is the recommended installation option. Use this option if you are a developer who wants to experience the app and the code.

• Installing Apex Recipes Using an Unlocked Package: This option allows anybody to experience the sample app without installing a local development environment.

• Installing Apex Recipes using a Developer Edition Org or a Trailhead Playground via the Salesforce CLI: Useful when tackling Trailhead Badges or if you want the app deployed to a more permanent environment than a Scratch org.

• Optional installation instructions

Installing the app using a Scratch Org

1. Set up your environment. Follow the steps in the Quick Start: Lightning Web Components Trailhead project. The steps include:

   • Enable Dev Hub in your Trailhead Playground
   • Install Salesforce CLI
   • Install Visual Studio Code
   • Install the Visual Studio Code Salesforce extensions

2. If you haven't already done so, authorize with your hub org and provide it with an alias (myhuborg in the command below):

   sf org login web -d -a myhuborg
   

3. Clone the apex-recipes repository:

   git clone https://github.com/trailheadapps/apex-recipes
   cd apex-recipes
   

4. Create a scratch org and provide it with an alias (apex-recipes in the command below):

   sf org create scratch -d -f config/project-scratch-def.json -a apex-recipes
   

5. Push the app to your scratch org:

   sf project deploy start
   

6. Assign the Apex_Recipes permission set to the default user:

   sf org assign permset -n Apex_Recipes
   

7. Assign the Walkthroughs permission set to the default user:

   sf org assign permset -n Walkthroughs
   

8. Import Sample Data

   sf data tree import -p ./data/data-plan.json
   sf data tree import -p ./data/data-plan2.json
   

9. Execute the Anonymous Apex setup script

   sf apex run --file data/setup.apex
   

10. Open the scratch org:

    sf org open
    

11. In App Launcher, select the Apex Recipes app.

Installing the app using an Unlocked Package

Follow this set of instructions if you want to deploy the app to a more permanent environment than a Scratch org or if you don't want to install the local developement tools. You can use a non source-tracked orgs such as a free Developer Edition Org or a Trailhead Playground.

Make sure to start from a brand-new environment to avoid conflicts with previous work you may have done.

1. Log in to your org

2. Go to Setup, under Platform Cache, and click the "Request Trial Capacity" button. Request a Platform Cache Trial

3. Click this link to install the Apex Recipes unlocked package in your org.

4. Select Install for All Users

5. Once installed:

6. (Optional) Add additional data examples. In the data folder are sample CSV files which can be used by dataloader.io or the Import Data Wizard.

7. (Optional) Load the sample Junction objects data:

   • Click the Setup Gear Icon
   • Click Developer Console
   • Click Debug
   • Click Open Execute Anonymous Window
   • Enter: DataFactoryForPackageInstalls.generateData();
   • Click Execute

8. Add the Apex Recipes permission set to your user:

   • Go to Setup > Users > Permission Sets.
   • Click Apex_Recipes.
   • Click Manage Assignments.
   • Check your user and click Add Assignments.

9. In App Launcher, select the Apex Recipes app.

   • If the app does not load, please double check that the Apex Recipes permission set active on your user.

Installing the App using a Developer Edition Org or a Trailhead Playground via the Salesforce CLI

Follow this set of instructions if you want to deploy the app to a more permanent environment than a Scratch org. This includes non source-tracked orgs such as a free Developer Edition Org or a Trailhead Playground.

Make sure to start from a brand-new environment to avoid conflicts with previous work you may have done.

1. Clone this repository:

   git clone https://github.com/trailheadapps/apex-recipes
   cd apex-recipes
   

2. Authorize with your Trailhead Playground or Developer Edition org and provide it with an alias (mydevorg in the command below):

   sf org login web -s -a mydevorg
   

3. If you are setting up a Developer Edition: go to Setup, under Platform Cache, and click the "Request Trial Capacity" button. Request a Platform Cache Trial

4. Run this command in a terminal to deploy the app.

   sf project deploy start -d force-app
   

5. Assign the Apex_Recipes permission set to the default user.

   sf org assign permset -n Apex_Recipes
   

6. Import Sample Data

   sf data tree import -p ./data/data-plan.json
   sf data tree import -p ./data/data-plan2.json
   

7. Execute the Anonymous Apex setup script

   sf apex run --file data/setup.apex
   

8. If your org isn't already open, open it now:

   sf org open -o mydevorg
   

9. In App Launcher, select the Apex Recipes app.

   • If the app does not load, please double check that the Apex Recipes permission set active on your user.

Optional Installation Instructions

This repository contains several files that are relevant if you want to integrate modern web development tooling to your Salesforce development processes, or to your continuous integration/continuous deployment processes.

Code formatting

Prettier is a code formatter used to ensure consistent formatting across your code base. To use Prettier with Visual Studio Code, install this extension from the Visual Studio Code Marketplace. The .prettierignore and .prettierrc files are provided as part of this repository to control the behavior of the Prettier formatter.

Warning The current Apex Prettier plugin version requires that you install Java 11 or above.

Code linting

ESLint is a popular JavaScript linting tool used to identify stylistic errors and erroneous constructs. To use ESLint with Visual Studio Code, install this extension from the Visual Studio Code Marketplace. The .eslintignore file is provided as part of this repository to exclude specific files from the linting process in the context of Lighning Web Components development.

Apex Docs

ApexDocs is a NPM package for generating Markdown (.md) files from the Classes in this repository. The package.json file in this repo includes an npm script for generating these Apex docs. Execute npm run apexdocs to generate fresh docs. These docs are shipped as part of a Static Resource and are available in your org via the Apex Recipes app. Navigate to any class and click it's coresponding Docs tab.

Pre-commit hook

This repository also comes with a package.json file that makes it easy to set up a pre-commit hook that enforces code formatting and linting by running Prettier and ESLint every time you git commit changes.

To set up the formatting and linting pre-commit hook:

1. Install Node.js if you haven't already done so
2. Run npm install in your project's root folder to install the ESLint and Prettier modules (Note: Mac users should verify that Xcode command line tools are installed before running this command.)

Note: This projects also contains Jest tests for unit testing Lightning Web Components. If you experience errors regarding deasync when running npm install please check out the troubleshooting information in the lwc-jest repository.

Prettier and ESLint will now run automatically every time you commit changes. The commit will fail if linting errors are detected. You can also run the formatting and linting from the command line using the following commands (check out package.json for the full list):

npm run lint
npm run prettier