WordsOfWisdom

A Node.js Single Page Application (SPA) that displays inspirational quotes from a custom Salesforce object.

Features

• Fetches quotes from a Salesforce custom object via API
• Clean, responsive UI with card-based quote display
• Real-time loading states and error handling
• Express.js backend to proxy Salesforce API calls

Prerequisites

• Node.js 18.x or higher
• A Salesforce account with API access
• A Salesforce Connected App for OAuth2 authentication (see Salesforce Setup below)
• A custom Quote object in Salesforce (see Salesforce Setup below)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/WordsOfWisdom.git
   cd WordsOfWisdom

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env

   Edit .env with your Salesforce credentials (see Configuration section).

4. Start the application:

   npm start

5. Open your browser and navigate to http://localhost:3000

Configuration

Create a .env file in the root directory with the following variables:

Variable	Description
SF_LOGIN_URL	Salesforce login URL (default: https://login.salesforce.com). Use https://test.salesforce.com for sandbox orgs.
SF_USERNAME	Your Salesforce username
SF_PASSWORD	Your Salesforce password + security token
SF_CLIENT_ID	OAuth2 Consumer Key from your Connected App
SF_CLIENT_SECRET	OAuth2 Consumer Secret from your Connected App
PORT	Server port (default: 3000)

Salesforce Setup

Salesforce package installation

This app relies on the availability of a Salesforce database. In order to create one and add your own quotes, please:

1. Login to a Salesforce instance (Sign Up for a Developer Edition org if needed)
2. Paste the following at the end of your Salesforce instance URL: /packagingSetupUI/ipLanding.app?apvId=04t6S000000YP58QAG (this will install the Quotes custom object in the namespace the app expects)
3. Use installation key 2ddPaXrxUNE6rJ
4. Assign your user the Quotes custom permission set
5. Navigate to the Quotes application using the Salesforce App Launcher waffle
6. Enter your own quotes

Connected App (Required for OAuth2)

This application uses OAuth2 Username-Password Flow for authentication. You need to create a Connected App in Salesforce:

1. Go to Setup > App Manager > New Connected App
2. Fill in the basic information:
   • Connected App Name: WordsOfWisdom
   • API Name: WordsOfWisdom
   • Contact Email: Your email
3. Enable OAuth Settings:
   • Check Enable OAuth Settings
   • Callback URL: https://login.salesforce.com/services/oauth2/callback (or your instance URL)
   • Selected OAuth Scopes: Add Full access (full) or at minimum Access and manage your data (api)
4. Click Save and wait a few minutes for the app to be created
5. Go to Manage Consumer Details to view and copy:
   • Consumer Key → Use as SF_CLIENT_ID
   • Consumer Secret → Use as SF_CLIENT_SECRET

Custom Object

The application expects a custom Salesforce object with API name Quotes__Quote__c containing the following fields:

• Quotes__Text__c (Long Text Area) - The quote text
• Quotes__Order__c (Number) - The display order for quotes

Create Sample Records

Add some quote records to your custom object with the Quotes__Text__c and Quotes__Order__c fields populated.

Security Token

If you don't have a security token or need to reset it:

1. Go to Settings > Reset My Security Token
2. Append the security token to your password in the .env file

API Endpoints

Endpoint	Method	Description
/api/quotes	GET	Fetch all quotes from Salesforce
/api/health	GET	Health check endpoint

Project Structure

WordsOfWisdom/
├── public/
│   ├── index.html      # Main HTML page
│   ├── styles.css      # Application styles
│   └── app.js          # Frontend JavaScript
├── src/
│   ├── server.js       # Express server
│   └── salesforceService.js  # Salesforce API service
├── .env.example        # Environment variables template
├── package.json        # Node.js dependencies
└── README.md           # This file

License

ISC

Running in GitHub Codespaces

1. Open the repository in GitHub Codespaces (click Code > Codespaces > Create codespace on main)

2. Once the Codespace is ready, open the terminal and install dependencies:

   npm install

3. Create your environment file:

   cp .env.example .env

4. Edit .env with your Salesforce credentials:

   SF_LOGIN_URL=https://login.salesforce.com
   SF_USERNAME=your_username@example.com
   SF_PASSWORD=your_password_and_security_token
   SF_CLIENT_ID=your_connected_app_consumer_key
   SF_CLIENT_SECRET=your_connected_app_consumer_secret

5. Start the application:

   npm start

6. Codespaces will prompt you to open the app in browser or forward the port. Click Open in Browser to view the application.

Deploying to a Web Host

Option 1: Heroku

1. Install the Heroku CLI

2. Login and create app:

   heroku login
   heroku create your-app-name

3. Set environment variables:

   heroku config:set SF_LOGIN_URL=https://login.salesforce.com
   heroku config:set SF_USERNAME=your_username@example.com
   heroku config:set SF_PASSWORD=your_password_and_security_token
   heroku config:set SF_CLIENT_ID=your_connected_app_consumer_key
   heroku config:set SF_CLIENT_SECRET=your_connected_app_consumer_secret

4. Deploy:

   git push heroku main

Option 2: Railway / Render / Vercel

1. Connect your GitHub repository to the hosting platform
2. Set the environment variables (SF_LOGIN_URL, SF_USERNAME, SF_PASSWORD, SF_CLIENT_ID, SF_CLIENT_SECRET) in the platform's dashboard
3. Deploy - most platforms auto-detect Node.js and run npm start

Option 3: Traditional VPS (DigitalOcean, AWS EC2, etc.)

1. SSH into your server and clone the repository:

   git clone https://github.com/yourusername/WordsOfWisdom.git
   cd WordsOfWisdom

2. Install Node.js (if not already installed) and dependencies:

   npm install

3. Create and configure .env file with your Salesforce credentials

4. Use a process manager like PM2 to run the app:

   npm install -g pm2
   pm2 start src/server.js --name wordsofwisdom

5. Set up a reverse proxy (nginx) to serve the app on port 80/443