Skip to content

Home

Jump to bottom
Jennifer Bennett edited this page Jun 16, 2020 · 2 revisions

The Program Management Module team plans to accept pull requests, provided they are:

  1. Non-trivial: That pull request that just has a comment with your name in it? Notsomuch.
  2. Support an open architecture: We want to support an open ecosystem. So integrating with a particular 3rd party service is great, but lets make sure we can integrate with every service, not just one.
  3. Non-superfluous: I've always wanted to build a version of Pacman in Apex/VF, but lets face it, probably not a great fit for the PMM, right?

Easiest way to make sure your pull request will be accepted is to just ask! Log an issue, or comment on an existing issue. Make mention of what you'd like to work on, and a member of the core contributor team will be happy to help vet your proposal, make suggestion or provide guidance throughout the process. Below, you'll find resources on how to get started, links to our code documentation, and a technical overview of the NPSP build system. Good luck, and happy coding!

Development

Use the following commands to create a PMM scratch org with or without the following options:

  • PMM only: cci flow run dev_org --org dev
  • PMM namespaced only: cci flow run dev_org_namespaced --org dev_namespaced
  • PMM + NPSP: cci flow run dev_org --org npsp
  • PMM namespaced + NPSP: cci flow run dev_org_namespaced --org npsp_namespaced

Code Formatting

We are in trial to use prettier and prettier-plugin-apex to format our classes, lwc, and aura.

Why Prettier?

By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles. It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process. People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.

So why choose the "Prettier style guide" over any other random style guide? Because Prettier is the only "style guide" that is fully automatic. Even if Prettier does not format all code 100% the way you'd like, it's worth the "sacrifice" given the unique benefits of Prettier, don't you think?

Plus, check out Prettier's Option Philosophy and Rationale.

How to install prettier and prettier-plugin-apex

  1. Install yarn

Installing yarn with brew is recommended: brew install yarn

  1. Call yarn install in the terminal.

See yarn install documentation for more options. For example, calling yarn install --check-files verifies that already installed files in node_modules did not get removed. If you've already called yarn install and you want to "reinstall", delete the node_modules directory (e.g. rm -rf node_modules) and call yarn install again.

And that's it! 🎉

Behind the scenes the following packages are also installed:

How to use prettier and prettier-plugin-apex

Our (very few) prettier configurations are stored in .prettierrc.yml. tl;dr:

  • Our print width is 90: not too big, not too small.
  • We want to use prettier-plugin-apex to format Apex Classes, Trigger, and Execute Anonymous Scripts.
  • Use the correct, associated prettier parser for our lwc, aura, classes, and *.apex Execute Anonymous scripts.

Use the prettier CLI.

  • Call prettier --write path/to/**/*.{cls,apex,js,html} to format the files specified in the path.
  • Call prettier --check path/to/**/*.{cls,apex,js,html} to check if the files specified in the path will change if formatted.
  • Call prettier --debug-check path/to/**/*.{cls,apex,js,html} to check if formatting will change the correctness of the files specified in the path.

Ignoring Code

Prettier offers an escape hatch to ignore a block of code or prevent entire files from being formatted.

Ignoring Files

To exclude files from formatting, add entries to a .prettierignore file in the project root or set the --ignore-path CLI option. .prettierignore uses gitignore syntax.

JavaScript

A JavaScript comment of // prettier-ignore will exclude the next node in the abstract syntax tree from formatting.

For example:

matrix(
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)

// prettier-ignore
matrix(
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)

will be transformed to:

matrix(1, 0, 0, 0, 1, 0, 0, 0, 1);

// prettier-ignore
matrix(
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)

JSX (e.g. LWC)

<div>
  {/* prettier-ignore */}
  <span     ugly  format=''   />
</div>

HTML

<!-- prettier-ignore -->
<div         class="x"       >hello world</div            >

<!-- prettier-ignore-attribute -->
<div
  (mousedown)="       onStart    (    )         "
  (mouseup)="         onEnd      (    )         "
></div>

<!-- prettier-ignore-attribute (mouseup) -->
<div
  (mousedown)="onStart()"
  (mouseup)="         onEnd      (    )         "
></div>

CSS

/* prettier-ignore */
.my    ugly rule
{

}

Markdown

<!-- prettier-ignore -->
Do   not    format   this

Can I automatically format files every time I save in my text editor?

Probably. 👍

See the instructions below. Please contribute how you automatically format files with prettier every time you save a file in your text editor.

VS Code

  1. Install the Prettier - Code formatter VS Code Extension.
  2. Change the Editor: Default Formatter to esbenp.prettier-vscode
    • Or add "editor.defaultFormatter": "esbenp.prettier-vscode" to your settings.json
  3. Check Editor: Format On Save
    • Or add "editor.formatOnSave": true to your settings.json
  4. Prettifying files can take ~1 s. Update Editor: Format On Save Timeout to 2000.
    • Or add "editor.formatOnSaveTimeout": 5000 to your settings.json
    • If you notice files not formatting after saving, try increasing upir Editor: Format On Save Timeout. Maybe, prettier is completing before timing out.
  5. Save a file. :bowtie:. Our prettier configuration at .prettierrc.yml should be honored.

Bonuses

  • Even though we've configured VS Code to format each file upon save, there is a VS Code command if you want to save a file without formatting. Press Command + Shift + P to search for commands, then search for Files: Save without Formatting.

Troubleshooting

If you are trying to call command Format Document an Apex Class in VS Code but get an error similar to "parser not found", try the following:

  • In the terminal, call yarn install --check-files. Yarn will make sure node_modules contains the necessary files.
  • Quit VS Code and restart for VS Code to refresh it's configuration and our .prettierrc.yml configuration.

Apex Anonymous woes

When trying the Format Document command on an Apex Anonymous file, e.g. scripts/*.apex, I get an error:

There is no formatter for 'apex-anon'-files installed.

I can't figure out how to associate Apex Anonymous (apex-anon) files with the esbenp.prettier-vscode formatter, i.e. update settings.json with

"[apex-anon]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
}

Workarounds

  • Use the command line: prettier --write scripts/[file name].apex
  • In VS Code, change the file format to Apex (which will give linting errors), execute Format Document which honors our .prettierrc.yml to prettify with apexAnonymous: true, then change the file format back to Apex Anonymous.

Attempt to associate Apex Anonymous (apex-anon) with a formatter in settings.json

IntelliJ

The Salesforce-focused plugin for IntelliJ called Illuminated Cloud has its own code formatting tools, but to keep consistency with other IDEs, we will use the separate IntelliJ plugin for Prettier. Initial setup instructions to install the plugin are here.

If you've followed the initial setup steps above, the Prettier application is in /node_modules/prettier within your local repo directory.

To manually apply rules to a file, press ⇧⌥⌘P.

To auto-apply rules on save, first install the File Watchers plugin. Then follow these instructions to create two File Watcher configs using the Prettier template, one for Apex Classes files and one for Javascript files.

Clone this wiki locally