agentgill/bad-ass-salesforce-stack

B.A.S.S. Starter: react / redux / typescript / antd / ts-force / sfdx / webpack / salesforce

B . A . S . S .

BAD ASS SALESFORCE STACK

• react: all the cool kids are doing it
• 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 w/ local asset on VisualForce page
• develop on localhost (REST API only)
• Hot Module Reloading (HMR)!
• 1 step build & deploy to orgs
• works with for developer, sandbox, scratch and even production orgs
• type safety 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 authentication 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

1. git clone https://github.com/ChuckJonas/bad-ass-salesforce-stack bass
2. cd bass
3. optional: git checkout the redux-example or react-example branches
4. 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 [ORG_URL] -a [ALIAS]. 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. You can use either the alias or the username here.

dev_alias=dev_username
scratch_alias=test_new_feature
prod_alias=prod_user

*NOTE: You might want to ignore .npmrc for your repo. Each contributor will manage this configuration separately and committing it could result in another user accidentally deploying to an unintended org. This is especially true if you use the sfdx alias over the username

Default Target

While deploy scripts are env specific, some commands (eg: npm start-local, npm enable-cors) use the default DX user. You can use following scripts to switch the default user to the desired alias listed in .npmrc

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

DEVELOPMENT

Salesforce w/ Local Assets

The most flexible development setup is to use localhost to serve assets on your VF page in salesforce. You'll be able to make changes from your IDE and salesforce will automatically update on the fly. Updates will only show for you and not impact any other users in that environment. You will not be limited from using any salesforce features you might need.

1. Deploy your application (step needs to happen whenever the contents of force-app change)
2. npm run start-sfdc (or just npm start)
3. navigate to your page EG: /apex/app
4. append ?local=1 to page query string
5. your browser will likely fail to load your resources. Follow this guide on how to make your system trust the localhost cert. Alternately, you can open the asset url, click advanced and then "proceed anyways". However, you will have to repeat this step often.

How it works

You can see how this is configured by looking at force-app/main/default/pages/App.page. Basically, we have two output panels that render conditionally based on the url param local == 1.

Localhost

This starter is also configured with the ability to run completely on localhost. While there are many benefits to local dev, you will be limited to communicating with salesforce ONLY through the REST API (@RemoteAction, Custom Controllers, Streaming API, etc will not run on locally host).

1. npm run cors-enable (only need to run once. whitelist localhost CORS on the default target org). See Warning[^1]
2. npm run start-local (start a local webserver with hot reload)

Localhost dev is really helpful for prototyping and even full applications depending on the requirements. If you are only using the REST API and your App.page doesn't change often, this might be the more convenient development setup.

How it works

• webpack will use SFDX to grab a session token & host from your current "default user" (can be changed via npm run make-[target]-default) and inject it into the global scope
• the config/index.html file will act like the VF pages (this always needs to reflect your setup in App.page)
  • if you inject any other variables into the global scope, you will also need to include these

[^1] 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 production 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?*

Hot Module Reloading (HMR)

Regardless of which development setup you use, you can take advantage of Hot Module Reloading (HMR), which allows updates to show up within seconds without ever having to refresh the page. Your application state is even also preserved in many cases. See HMR in action.

Deployment

This starter offers 1 step 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:

1. rm -r -f .git (WARNING: no going back!)
2. git init
3. optionally add git remote
4. configure & npm run ts-force-generate
5. rename page & resource bundle (optional)
6. 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 generated Static Resource

1. in package.json update resource under config section
2. optionally, update your .gitignore to exclude these files
3. finally, just update your vf page to properly reference the new resource name

**NOTE: If you include other static resources in the force-app/main/default/staticresources folder they will get nuked by default. To prevent this, update the copy-bundle script **

OTHER CONFIGURATIONS

antd theming

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

ts-force configuration

This project comes equipped with ts-force to allow you to access Salesforce 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 documentation.

changing localhost port

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

1. In /config/webpack.config.json update the PORT constant
2. In /config/sfdc-cors-enable update it on both files
3. in /force-app/main/default/pages/App.Page, update the "Local Asset" panel

    <apex:outputPanel layout="none" rendered="{!$CurrentPage.parameters.local == '1'}">
        <script src="https://localhost:8080/vendors.js" ></script>
        <script src="https://localhost:8080/app.js" ></script>
    </apex:outputPanel>

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

OTHER USEFUL STUFF

vscode

Highly recommend using vscode (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
• Webpack Dashboard App: nice app for you webpack-dev-server status

helpful linkies

• typescript deep dive
• react-redux-typescript-guide
• jest reference
• sfdx cli reference
• React-Redux: put API calls in the correct place
• Where to Hold React Component Data: state, store, static, and this
• Redux: How to chain async actions
• a-redux-typescript-setup
• Idiomatic Redux: Thoughts on Thunks, Sagas, Abstraction, and Reusability

The MIT License (MIT)

Copyright (c) 2017 Charlie Jonas charlie@callaway.cloud

Expanded from react-redux-typescript-webpack-starter

Copyright (c) 2016 Piotr Witek piotrek.witek@gmail.com (http://piotrwitek.github.io/)