{"id":29861377,"url":"https://github.com/heroku-reference-apps/applink-getting-started-nodejs","last_synced_at":"2026-05-04T20:32:11.532Z","repository":{"id":304854075,"uuid":"1016976095","full_name":"heroku-reference-apps/applink-getting-started-nodejs","owner":"heroku-reference-apps","description":"Heroku AppLink Sample App with Node.js and Fastify","archived":false,"fork":false,"pushed_at":"2025-07-15T16:02:50.000Z","size":146,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T11:09:51.399Z","etag":null,"topics":["applink","fastify","heroku","nodejs","salesforce"],"latest_commit_sha":null,"homepage":"https://devcenter.heroku.com/articles/heroku-applink","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heroku-reference-apps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-09T20:34:00.000Z","updated_at":"2025-07-15T16:11:01.000Z","dependencies_parsed_at":"2025-07-16T16:08:06.930Z","dependency_job_id":"a088ecc5-b0a5-439b-bdc4-5992330299aa","html_url":"https://github.com/heroku-reference-apps/applink-getting-started-nodejs","commit_stats":null,"previous_names":["heroku-reference-apps/applink-getting-started-nodejs"],"tags_count":null,"template":false,"template_full_name":"salesforce/oss-template","purl":"pkg:github/heroku-reference-apps/applink-getting-started-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku-reference-apps%2Fapplink-getting-started-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku-reference-apps%2Fapplink-getting-started-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku-reference-apps%2Fapplink-getting-started-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku-reference-apps%2Fapplink-getting-started-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heroku-reference-apps","download_url":"https://codeload.github.com/heroku-reference-apps/applink-getting-started-nodejs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku-reference-apps%2Fapplink-getting-started-nodejs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267814099,"owners_count":24148325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["applink","fastify","heroku","nodejs","salesforce"],"created_at":"2025-07-30T05:01:19.337Z","updated_at":"2026-05-04T20:32:11.525Z","avatar_url":"https://github.com/heroku-reference-apps.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heroku AppLink Node.js App Template\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/heroku-reference-apps/applink-getting-started-nodejs)\n\nThe Heroku AppLink Node.js app template is a [Fastify](https://fastify.dev/) 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.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Local Development](#local-development)\n- [Testing with invoke.sh](#testing-with-invokesh)\n- [Manual Heroku Deployment](#manual-heroku-deployment)\n- [Heroku AppLink Setup](#heroku-applink-setup)\n- [Project Structure](#project-structure)\n- [API Documentation](#api-documentation)\n- [Additional Resources](#additional-resources)\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20.x or later\n- npm\n- Git\n- Heroku CLI (for deployment)\n- Salesforce org (for AppLink integration)\n\n### Deploy to Heroku (One-Click)\n\nClick the Deploy button above to deploy this app directly to Heroku with the AppLink add-on pre-configured.\n\n## Local Development\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/heroku-reference-apps/applink-getting-started-nodejs.git\ncd applink-getting-started-nodejs\nnpm install\n```\n\n### 2. Start the Development Server\n\n```bash\n# Start with auto-reload and debug logging\nnpm run dev\n\n# Or start production mode\nnpm start\n```\n\nYour app will be available at `http://localhost:3000`\n\n### 3. API Endpoints\n\n- **GET /accounts** - Retrieve Salesforce accounts from the invoking org\n- **POST /unitofwork** - Create a unit of work for Salesforce\n- **POST /handleDataCloudDataChangeEvent** - Handle a Salesforce Data Cloud Change Event\n- **GET /api-docs** - Interactive Swagger UI for API documentation\n- **GET /health** - Health check endpoint\n\n### 4. View API Documentation\n\nVisit `http://localhost:3000/api-docs` to explore the interactive API documentation powered by Swagger UI.\n\n## Testing locallywith invoke.sh\n\nThe `bin/invoke.sh` script allows you to test your locally running app with proper Salesforce client context headers.\n\n### Usage\n\n```bash\n./bin/invoke.sh ORG_DOMAIN ACCESS_TOKEN ORG_ID USER_ID [METHOD] [API_PATH] [DATA]\n```\n\n### Parameters\n\n- **ORG_DOMAIN**: Your Salesforce org domain (e.g., `mycompany.my.salesforce.com`)\n- **ACCESS_TOKEN**: Valid Salesforce access token\n- **ORG_ID**: Salesforce organization ID (15 or 18 characters)\n- **USER_ID**: Salesforce user ID (15 or 18 characters)\n- **METHOD**: HTTP method (default: GET)\n- **API_PATH**: API endpoint path (default: /accounts)\n- **DATA**: JSON data for POST/PUT requests\n\n### Examples\n\n```bash\n# Test the accounts endpoint\n./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC\n\n# Test with POST data\n./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC POST /accounts '--data \"{\\\"name\\\":\\\"Test Account\\\"}\"'\n\n# Test custom endpoint\n./bin/invoke.sh mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC GET /health\n```\n\n### Getting Salesforce Credentials\n\nTo get the required Salesforce credentials for testing:\n\n1. **Access Token**: Use Salesforce CLI to generate a session token\n2. **Org ID**: Found in Setup → Company Information\n3. **User ID**: Found in your user profile or Setup → Users\n\n## Manual Heroku Deployment\n\n### 1. Prerequisites\n\n- [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) installed\n- Git repository initialized\n- Heroku account with billing enabled (for add-ons)\n\n### 2. Create Heroku App\n\n```bash\n# Create a new Heroku app\nheroku create your-app-name\n\n# Or let Heroku generate a name\nheroku create\n```\n\n### 3. Add Required Buildpacks\n\nThe app requires two buildpacks in the correct order:\n\n```bash\n# Add the AppLink Service Mesh buildpack first\nheroku buildpacks:add heroku/heroku-applink-service-mesh\n\n# Add the Node.js buildpack second\nheroku buildpacks:add heroku/nodejs\n```\n\n### 4. Provision the AppLink Add-on\n\n```bash\n# Provision the Heroku AppLink add-on\nheroku addons:create heroku-applink\n\n# Set the required HEROKU_APP_ID config var\nheroku config:set HEROKU_APP_ID=\"$(heroku apps:info --json | jq -r '.app.id')\"\n```\n\n### 5. Deploy the Application\n\n```bash\n# Deploy to Heroku\ngit push heroku main\n\n# Check deployment status\nheroku ps:scale web=1\nheroku open\n```\n\n### 6. Verify Deployment\n\n```bash\n# Check app logs\nheroku logs --tail\n```\n\n## Heroku AppLink Setup\n\n### 1. Install AppLink CLI Plugin\n\n```bash\n# Install the AppLink CLI plugin\nheroku plugins:install @heroku-cli/plugin-applink\n```\n\n### 2. Connect to Salesforce Org\n\n```bash\n# Connect to a production org\nheroku salesforce:connect production-org --addon your-addon-name -a your-app-name\n\n# Connect to a sandbox org\nheroku salesforce:connect sandbox-org --addon your-addon-name -a your-app-name --login-url https://test.salesforce.com\n```\n\n### 3. Authorize a User\n\n```bash\n# Authorize a Salesforce user for API access\nheroku salesforce:authorizations:add auth-user --addon your-addon-name -a your-app-name\n```\n\n### 4. Publish Your App\n\n```bash\n# Publish the app to Salesforce as an External Service\nheroku salesforce:publish api-spec.yaml \\\n  --client-name MyAPI \\\n  --connection-name production-org \\\n  --authorization-external-client-app-name MyAppExternalClientApp \\\n  --authorization-permission-set-name MyAppPermissions \\\n  --addon your-addon-name\n```\n\n### 5. Required Salesforce Permissions\n\nUsers need the \"Manage Heroku AppLink\" permission in Salesforce:\n\n1. Go to Setup → Permission Sets\n2. Create a new permission set or edit existing\n3. Add \"Manage Heroku AppLink\" system permission\n4. Assign the permission set to users\n\n### 6. AppLink Buildpack Details\n\nThe `heroku/heroku-applink-service-mesh` buildpack provides:\n\n- **Service Mesh Proxy**: Handles authentication and authorization\n- **Request Validation**: Validates incoming Salesforce requests\n- **Header Management**: Manages Salesforce client context headers\n- **Security**: Ensures secure communication between Salesforce and your app\n\nThe service mesh runs on a separate port and proxies requests to your app, adding the necessary Salesforce context.\n\n### 7. Connecting to Different Org Types\n\n#### Production/Developer Orgs\n\n```bash\nheroku salesforce:connect prod-org --login-url https://login.salesforce.com\n```\n\n#### Sandbox Orgs\n\n```bash\nheroku salesforce:connect sandbox-org --login-url https://test.salesforce.com\n```\n\n#### Data Cloud Integration\n\n```bash\nheroku datacloud:connect datacloud-org --addon your-addon-name -a your-app-name\n```\n\n#### JWT Authentication (CI/CD)\n\n```bash\nheroku salesforce:connect:jwt cicd-org \\\n  --client-id YOUR_CLIENT_ID \\\n  --jwt-key-file path/to/server.key \\\n  --username your-username@company.com \\\n  --login-url https://login.salesforce.com\n```\n\n### Available Scripts\n\n```bash\nnpm start          # Start production server\nnpm run dev        # Start development server with auto-reload\nnpm test           # Run test suite\nnpm run lint       # Run ESLint\nnpm run lint:fix   # Fix ESLint errors\nnpm run format     # Format code with Prettier\n```\n\n## Additional Resources\n\n### Documentation\n\n- [Getting Started with Heroku AppLink](https://devcenter.heroku.com/articles/getting-started-heroku-applink)\n- [Working with Heroku AppLink](https://devcenter.heroku.com/articles/working-with-heroku-applink)\n- [Heroku AppLink CLI Plugin](https://devcenter.heroku.com/articles/heroku-applink-cli)\n- [Fastify Documentation](https://fastify.dev/)\n\n### Integration Guides\n\n- [Heroku AppLink and Salesforce](https://devcenter.heroku.com/articles/getting-started-heroku-applink-salesforce)\n- [Heroku AppLink and Data Cloud](https://devcenter.heroku.com/articles/getting-started-heroku-applink-data-cloud)\n- [Heroku AppLink and Agentforce](https://devcenter.heroku.com/articles/getting-started-heroku-applink-agentforce)\n\n### Support\n\n- [Heroku AppLink Reference](https://devcenter.heroku.com/articles/heroku-applink-reference)\n- [Heroku Support](https://help.heroku.com/)\n- [Salesforce Developer Community](https://developer.salesforce.com/)\n\n---\n\n**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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku-reference-apps%2Fapplink-getting-started-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheroku-reference-apps%2Fapplink-getting-started-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku-reference-apps%2Fapplink-getting-started-nodejs/lists"}