The Heroku AppLink Node.js app template is a Fastify web application that demonstrates how to build APIs for Salesforce integration using Heroku AppLink. This template includes authentication, authorization, and API specifications for seamless integration with Salesforce, Data Cloud, and Agentforce.
- Quick Start
- Local Development
- Testing with invoke.sh
- Manual Heroku Deployment
- Heroku AppLink Setup
- Project Structure
- API Documentation
- Additional Resources
- Node.js 20.x or later
- npm
- Git
- Heroku CLI (for deployment)
- Salesforce org (for AppLink integration)
Click the Deploy button above to deploy this app directly to Heroku with the AppLink add-on pre-configured.
git clone https://github.com/heroku-reference-apps/applink-getting-started-nodejs.git
cd applink-getting-started-nodejs
npm install# Start with auto-reload and debug logging
npm run dev
# Or start production mode
npm startYour app will be available at http://localhost:3000
- GET /accounts - Retrieve Salesforce accounts from the invoking org
- POST /unitofwork - Create a unit of work for Salesforce
- POST /handleDataCloudDataChangeEvent - Handle a Salesforce Data Cloud Change Event
- GET /api-docs - Interactive Swagger UI for API documentation
- GET /health - Health check endpoint
Visit http://localhost:3000/api-docs to explore the interactive API documentation powered by Swagger UI.
The bin/invoke.sh script allows you to test your locally running app with proper Salesforce client context headers.
./bin/invoke.sh ORG_DOMAIN ACCESS_TOKEN ORG_ID USER_ID [METHOD] [API_PATH] [DATA]- ORG_DOMAIN: Your Salesforce org domain (e.g.,
mycompany.my.salesforce.com) - ACCESS_TOKEN: Valid Salesforce access token
- ORG_ID: Salesforce organization ID (15 or 18 characters)
- USER_ID: Salesforce user ID (15 or 18 characters)
- METHOD: HTTP method (default: GET)
- API_PATH: API endpoint path (default: /accounts)
- DATA: JSON data for POST/PUT requests
# Test the accounts endpoint
./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC
# Test with POST data
./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC POST /accounts '--data "{\"name\":\"Test Account\"}"'
# Test custom endpoint
./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC GET /healthTo get the required Salesforce credentials for testing:
- Access Token: Use Salesforce CLI to generate a session token
- Org ID: Found in Setup → Company Information
- User ID: Found in your user profile or Setup → Users
- Heroku CLI installed
- Git repository initialized
- Heroku account with billing enabled (for add-ons)
# Create a new Heroku app
heroku create your-app-name
# Or let Heroku generate a name
heroku createThe app requires two buildpacks in the correct order:
# Add the AppLink Service Mesh buildpack first
heroku buildpacks:add heroku/heroku-applink-service-mesh
# Add the Node.js buildpack second
heroku buildpacks:add heroku/nodejs# Provision the Heroku AppLink add-on
heroku addons:create heroku-applink
# Set the required HEROKU_APP_ID config var
heroku config:set HEROKU_APP_ID="$(heroku apps:info --json | jq -r '.app.id')"# Deploy to Heroku
git push heroku main
# Check deployment status
heroku ps:scale web=1
heroku open# Check app logs
heroku logs --tail# Install the AppLink CLI plugin
heroku plugins:install @heroku-cli/plugin-applink# Connect to a production org
heroku salesforce:connect production-org --addon your-addon-name -a your-app-name
# Connect to a sandbox org
heroku salesforce:connect sandbox-org --addon your-addon-name -a your-app-name --login-url https://test.salesforce.com# Authorize a Salesforce user for API access
heroku salesforce:authorizations:add auth-user --addon your-addon-name -a your-app-name# Publish the app to Salesforce as an External Service
heroku salesforce:publish api-spec.yaml \
--client-name MyAPI \
--connection-name production-org \
--authorization-connected-app-name MyAppConnectedApp \
--authorization-permission-set-name MyAppPermissions \
--addon your-addon-nameUsers need the "Manage Heroku AppLink" permission in Salesforce:
- Go to Setup → Permission Sets
- Create a new permission set or edit existing
- Add "Manage Heroku AppLink" system permission
- Assign the permission set to users
The heroku/heroku-applink-service-mesh buildpack provides:
- Service Mesh Proxy: Handles authentication and authorization
- Request Validation: Validates incoming Salesforce requests
- Header Management: Manages Salesforce client context headers
- Security: Ensures secure communication between Salesforce and your app
The service mesh runs on a separate port and proxies requests to your app, adding the necessary Salesforce context.
heroku salesforce:connect prod-org --login-url https://login.salesforce.comheroku salesforce:connect sandbox-org --login-url https://test.salesforce.comheroku datacloud:connect datacloud-org --addon your-addon-name -a your-app-nameheroku salesforce:connect:jwt cicd-org \
--client-id YOUR_CLIENT_ID \
--jwt-key-file path/to/server.key \
--username [email protected] \
--login-url https://login.salesforce.comnpm start # Start production server
npm run dev # Start development server with auto-reload
npm test # Run test suite
npm run lint # Run ESLint
npm run lint:fix # Fix ESLint errors
npm run format # Format code with Prettier- Getting Started with Heroku AppLink
- Working with Heroku AppLink
- Heroku AppLink CLI Plugin
- Fastify Documentation
Note: This template is designed for educational purposes and as a starting point for building Salesforce-integrated applications. For production use, ensure proper error handling, security measures, and testing practices are implemented.