Skip to content

Latest commit

 

History

History
226 lines (147 loc) · 10.7 KB

README.md

File metadata and controls

226 lines (147 loc) · 10.7 KB
Raw

B . A . S . S .

NPM version

BAD ASS SALESFORCE STACK bass... like the fish

  • react: all the cool kids are doing it
  • typescript: business in the front, party in the back
  • antd: the best thing to come out of China since the fork
  • ts-force: generates massive files so you don't have toooo
  • vite: Does a lot of stuff won't ever fully don't understand, slightly better than webpack
  • sfdx-cli: #nosoftware

FEATURES

  • develop w/ local asset on VisualForce page
  • Hot Module Reloading (HMR)!
  • 1 step build & deploy to orgs
  • supports developer, sandbox, scratch and production orgs
  • type safety and code completion when working with SF objects
  • testing with vitest
  • setup for debugging in vscode chrome debugger

GETTING STARTED

System Requirements

Make sure you have the following installed on your machine:

  • npm
  • sfdx-cli: If you plan on developing against "scratch orgs", you will need to authorize a "hub".

Windows

You will also need the ability to execute the following bash commands: zip, cp, mv.

There are several options:

You may also need to tell npm to use bash: npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"

Install via Yeoman generator

First, install Yeoman and generator-bass using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-bass

Then generate your new project:

yo bass my-project
# ... answer questions
cd my-project
npm run deploy-dev # this will deploy code to your dev target org

Project Structure

  • app: The react Application source Folder
  • force-app: The Salesforce DX package. Store related metadata here. You can change this via yeoman prompt
  • config: configurations for development, build & tests (some configuration files are in root)
  • dist: the build directory

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

The starter supports 3 pre-defined "targets". Each target allow us to run different build & dev scripts depending on the context:

  • 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. Optimizes build

Targets are set in the .npmrc config file. You can use either the alias or the username here:

dev_alias=dev_username
scratch_alias=scratch
prod_alias=john@acme.com

*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

DEVELOPMENT

  1. Deploy your application by running npm run deploy-dev or npm run deploy-scratch. This step needs to happen whenever the contents of force-app change.
  2. run npm start
  3. Enable the Allow Insecure Localhost setting in chrome (chrome://flags/#allow-insecure-localhost). If you don't want to enable this, or use a different browser, you can create your own self-signed certificate by following these instructions.
  4. navigate to your page in salesforce: EG: /apex/app
  5. append ?local=1 to page query string
  6. Start coding. Your app will automatically update as you save changes.

See HMR in action

How it works

vite compiles and makes your app available @ https//localhost:PORT. It incrementally compiles your app as you make changes allows modules to be hot reloaded without refreshing the page.

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

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. build -> deploy process

Further Configuration

Renaming the VF Page

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

Note: You can have multiple VF pages

Renaming the Static Resource

  1. in package.json, under the config section, update resource
  2. optionally, update your .gitignore to exclude these files
  3. finally, just update $Resource.app in the 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 **

ts-force configuration

This project comes equipped with ts-force to allow you typed access to Salesforce Rest API. 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 .npmrc, under the devServerPort section
  2. in /force-app/main/default/pages/App.Page, update the "Local Asset" panel: https://localhost:XXXX/app.js.

TIP: If you need multiple devs working on different ports, update the page to pull port from a custom setting!

vscode Chrome Debugger

It is possible to debug right from vscode. To do so:

  1. install Debugger for Chrome
  2. update .vscode/launch.json -> url to reference the url you want to debug
  3. npm start
  4. f5 or launch debug locally configuration
  5. you may need to Enable Allow Insecure Localhost again if it opens in a different instance of chrome

Upgrading to newer version of "BASS"

Overtime, this project has gotten both simpler AND objectively better.

Unfortunately upgrades are currently a very manual process. Overtime:

  • configuration files have been changed & moved around
  • Low Value / High Complexity: features have been removed
  • build scripts have changed
  • configuration files have changed
  • npm dependencies have been upgraded/added/removed

I admit, I haven't done a very good job of documenting these changes very well. My goal of keeping this everything as flexible as possible has also made it impossible to move parts of the configuration to upgradable packages.

Upgrading to 2.0.0

Version 2.0.0 is a major upgrade to the project. It includes the following changes:

  • Upgrade to React18
  • Replace Webpack with Vite
  • Replacing Jest/Enzyme with Vitest/React Testing Library
  • Upgrade to antd v5 (changes to theming, removes LESS support by default)

The easiest way to upgrade is to start a new project and copy over your files.

OTHER USEFUL STUFF

vscode

Highly recommend using vscode (typescript code completion, in editor terminal, etc).

plugins:

helpful linkies

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/)