B . A . S . S .

BAD ASS SALESFORCE STACK

react: all the cool kids are doing it
redux: wizard state managment
typescript: business in the front, party in the back
antd: the most useful thing to come out of China since the fork
ts-force: generates massive files so you don't have toooo
webpack: Does a lot of stuff you fully don't understand
sfdx-cli: #nosoftware

FEATURES

develop on localhost with Hot Module Reloading and "Real" salesforce data
develop w/ local asset on visualforce page
1 step build & prompt to orgs
works with for developer, sandbox, scratch and even production orgs
type safey and completion when working with SF objects
jest test framework
setup for Redux Developer tools (browser extension)
setup for debugging in vscode chrome debugger

GETTING STARTED

Install SFDC-cli

This workflow uses sfdx-cli to manage authinication and deployment of meta data to orgs. Run npm install --global sfdx-cli. You don't need to authorize a hub org unless you plan on developing against "scratch orgs".

Clone Starter

git clone https://github.com/ChuckJonas/bad-ass-salesforce-stack bass
cd bass
optional: git checkout the redux-example or react-example branches
npm install

Authentication

To do much of anything you'll need to connect with one or more orgs. Use sfdx force:org:list to see a list of orgs you're already authenticated with. Connect to an existing sandbox using sfdx force:auth:web:login -sr http://test.salesforce.com -a client_dev_sandbox. For production orgs, just drop the r param, sfdx force:auth:web:login -sa my_prod_org. You can also create a scratch org using: npm run new-scratch-org.

Setup Target Orgs

Several commands take advantage of the following predefined "targets"

dev: to develop against a traditional salesforce org. Developer or Sandbox
scratch: allows development against a "scratch org" using the Salesforce DX flow. Must authenticate with a hub org
prod: to release your app. Can also be used to hotfix with live production data. Don't be dumb and develop against production!

You'll need to specific the associated alias each target in the .npmrc config file.


dev_alias=client_dev_sandbox
scratch_alias=test_new_feature
prod_alias=my_prod_org

*NOTE: Don't track changes to .npmrc. Each contributor will manage this configuration separately and committing it could result in another user accidentally deploying to an unintended org.

Default Target

While deployment command are env specific, some commands (eg: npm start) use the default DX user. Use the following commands to change the defaults to the desired alias listed in .npmrc

npm run make-dev-default
npm run make-scratch-default
npm run make-prod-default

Deploy Meta-data

Before you can run the example app, you need to get depedent metadata into your target org. You can easily do this by running npm run deploy-dev OR npm run deploy-scratch.

DEVELOPMENT

Run Locally with HMR (hot module reloading)

One of the biggest benefits of this stack is the ability to work locally with real salesforce data! HMR allows updates to show up within seconds without ever having to refresh the page. Your state is even also preserved in most cases. See HMR in action.

One of the biggest benefits to local dev is the ability to keep your Sandbox in a UAT state, while you are activitly develping new features.

npm run cors-enable (only need to run once. whitelists localhost CORS on the default target org) DANGER (see "Danger Localhost CORS")*
npm start (start a local webserver with hot reload)

Run Remotely With Local Assets

Another option is to run your app in Salesforce, but using local copies of the app assets. You'll be able to make changes to the app and test inside the salesforce container page, but your changes will only show for you and not impact any other users in that environment. This is very helpful in ensuring your app runs in the SF org before deploying.

npm run cors-enable (only need to run once. whitelists localhost CORS on the default target org) DANGER (see "Danger Localhost CORS")*
npm run start-remote
append ?local=1 to page query string
browser may complain the first time. Open up script url and tell browser to f-off

Danger Localhost CORS

DANGER: while allowing salesforce to accept request from a localhost server is awesome for hot reloading it has security risks. It's best if you don't do this in a prodcution or org with sensitive data. But if you did, be sure to disable cors when done with npm run cors-disable to disable the security hole!!! why?*

Deployment

This starter offers 1 set build & deploy to each of the 3 targets.


npm run deploy-dev
npm run deploy-scratch
npm run deploy-prod

This diagram outlines the process.

Starting your own project

If you want to use this project as a template for your own simply:

rm -r -f .git (WARNING: no going back!)
git init
optionally add git remote
configure & run ts-force gen
rename page & resource bundle (optional)
remove example files

Renaming Page and Resource Bundle

Before you start your own project, you'll probably want to rename the page & resource bundle from App to something more specific.

Renaming the page is as simple as navigating to force-app/main/default/pages and renaming the .page and .page-meta.xml.

To rename the Static Resource:

rename force-app/main/default/staticresource/App.resource-meta.xml
in package.json, find the copy-bundle and rename the copy target accordingly
finally, just update your vf page to properly reference the new resource name

OTHER CONFIGURATIONS

antd theming

You can change the antd theme less varibles by editing /styles/ant-theme-vars.less. Unforuntely changes require a webpack restart to show up :(

ts-force configuration

This project comes equiped with ts-force to allow you to access saleforce data in a typed manor. To use ts-force, you must first generate classes for the SObjects you want to work with.

You can do this by editing ts-force-config.json. Make sure auth: {username: ""} is set to the target org alias you want to use to generate classes. This should be the end user for the app!

For more details on configuration, see the ts-force documenation.

changing localhost port

Unforuntely the port isn't currently managed from a single point and must be updated in 2 places:

/config/webpack.config.json on the DEV_SERVER object
in /config/sfdc-cors-enable update it on both files.

if you change the port, don't forget to update salesforce w/ npm run cors-enable

OTHER USEFUL STUFF

vscode

Higly recommend using vcode (typescript code completion, in editor terminal, etc).

plugins:

Debugger for Chrome: Allows debugging in vscode
TSlint: green squigglies everywhere!
Salesforce Extensions for VS Code: gives your code completion on your force-app and ability to excute commands against the CLI
Auto Close Tag
Typescript Hero: auto-imports, etc
Jest: run tests on save

helpful linkies

The MIT License (MIT)

Expanded from react-redux-typescript-webpack-starter

ruslan-kurchenko / bad-ass-salesforce-stack Goto Github PK

bad-ass-salesforce-stack's Introduction