Getting Started with Lightning Web Components Open Source on Heroku

Introduction

Create and deploy a Lightning Web Components Open Source (LWC OSS) project on Heroku with this tutorial.

Pre-requisites

• A verified Heroku Account
• Node.js and npm installed locally
• Git installed locally.
• You are subscribed to the Eco dynos plan (recommended)

If you don’t already have Git installed, complete the following before proceeding:

• Git installation
• First-time Git setup

Install the Heroku CLI

Install the Heroku Command Line Interface (CLI). You use the CLI to manage and scale your applications, provision add-ons, view your recent application logs, and run your application locally.

Download and run the installer for your platform:

After installation completes, you can use the heroku command from your terminal.

Log In

Use the heroku login command to log in to the Heroku CLI:

$ heroku login
heroku: Press any key to open up the browser to login or q to exit
 ›   Warning: If browser does not open, visit
 ›   https://cli-auth.heroku.com/auth/browser/***
heroku: Waiting for login...
Logging in... done
Logged in as me@example.com

This command opens your web browser to the Heroku login page to complete authentication. If your browser is already logged in to Heroku, click the Log in button displayed on the page.

Both the heroku and git commands require this authentication to work correctly.

If you’re behind a firewall that requires a proxy to connect with external HTTP/HTTPS services, set the HTTP_PROXY or HTTPS_PROXY environment variables in your local development environment before running the heroku command.

Create an LWC Project

To create a Lightning Web Components project, use Lightning Web Runtime (LWR).

The tool guides you through a short setup and scaffolds a Lightning Web Components project.

$ npm init lwr        # Follow the on-screen instructions
                          # Select the "Single Page App" project
                          # Select the "LWC" option
$ cd ExampleLWCProjectName

Track Code in Git

While there are other deployment methods, the most common method for deploying code to Heroku is via git. Create a Git repository for your project and commit your files.

Create a Repo

Run this command to initialize a repository:

$ git init

Git still defaults to using master as the default branch name. To switch the default branch from master to main, create a new branch locally and delete the old branch:

$ git checkout -b main
$ git branch -D master

From there, the local environment only knows about the main branch. Commit your files to this branch.

Commit Files to Git

$ git add .
$ git commit -m “Initial commit”

You now have a local Git repo tracking your files.

Declare App Dependencies

Heroku recognizes your LWC project as a Node.js app by the existence of a package.json file in the root directory. When a Node.js app is detected, Heroku adds the official Node.js buildpack to your app, which installs the dependencies for your application.

Your project created by npm init lwr includes a package.json file similar to the following:

{
 "name": "example-lwc-project",
…
 },
 "dependencies": {
   "lwc": "2.5.8",
   "lwr": "0.6.5"
 },
 "engines": {
   "node": ">=14.15.4 <17"
 }
}

Install Local Dependencies

Run npm install in your local directory to install the dependencies, preparing your system for running the app locally:

$ npm install

A package-lock.json file auto-generates when you run npm install. When you deploy an app, Heroku reads the package.json to install the appropriate Node version and the package-lock.json to install the dependencies.

When you add new dependencies, npm install also makes the appropriate changes to this file. Ensure that you commit this file after the initial install or any subsequent changes to dependencies.

$ git add .
$ git commit -m "Added package-lock.json"

Add a Procfile

A Procfile is a special plaintext file used by Heroku apps to explicitly declare the processes and commands used to start your app.

Add a file named Procfile, with no file extension, to your project’s root directory. Add this line to the file:

web: npm run start

This line declares a single process type, web, and the command to run it. The name web is important. It declares that this process type attaches to Heroku’s HTTP routing stack, and can receive web traffic.

Procfiles can contain additional process types. For example, you can declare a background worker that processes items off a queue. This tutorial doesn’t cover other processes but you can refer to The Procfile and The Process Model for more info.

Remember to commit your file:

$ git add .
$ git commit -m “Added Procfile”

Run the App Locally

Ensure you’ve already run npm install before running your app locally.

Start your application locally with the heroku local CLI command:

$ heroku local --port 5001
...
3:31:05 p.m. web.1 |  > lwr-project@0.0.1 start
3:31:05 p.m. web.1 |  > lwr serve --mode prod
3:31:07 p.m. web.1 |  (node:4454) [DEP0111] DeprecationWarning: Access to process.binding('http_parser') is deprecated.
3:31:07 p.m. web.1 |  (Use `node --trace-deprecation ...` to show where the warning was created)
3:31:09 p.m. web.1 |   server running at: port: 5001 | mode: prod

Just like the Heroku platform, heroku local examines your Procfile to determine what command to run.

Open http://localhost:5001 with your web browser to see your app running locally.

To stop the app from running locally, go back to your terminal window and press CTRL+C to exit.

Deploy the App

Git remotes are versions of your repository that live on other servers. You deploy your app by pushing its code to a special Heroku-hosted remote that’s associated with your app.

Create a Heroku App and Git Remote

Create an app on Heroku to prepare it to receive your source code for deployment. This command both creates an app and a Git remote (named heroku) associated with your local Git repo:

$ heroku create --app example-lwc-project
Creating app... done, example-lwc-project
https://example-lwc-project-1234567890ab.herokuapp.com/ | https://git.heroku.com/example-lwc-project.git

By default, Heroku generates a random name for your app. You can pass the --app parameter to specify your own app name.

Deploy Your Code

 

Now deploy your code:

$ git push heroku main
Enumerating objects: 12971, done.
Counting objects: 100% (12971/12971), done.
Delta compression using up to 8 threads
Compressing objects: 100% (9805/9805), done.
Writing objects: 100% (12971/12971), 21.68 MiB | 9.62 MiB/s, done.
Total 12971 (delta 2486), reused 12971 (delta 2486)
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-20 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Node.js app detected
…
remote: Verifying deploy... done.
To https://git.heroku.com/example-lwc-project.git

You can now visit your app at your-app-name-1234567890ab.herokuapp.com.

Dyno Usage

A dyno is a lightweight Linux container that runs the command specified in your Procfile. After deployment, ensure that you have one web dyno running the app. You can check how many dynos are running using the heroku ps command. This example assumes you are subscribed to the Eco dynos plan:

$ heroku ps
Eco dyno hours quota remaining this month: 997h 48m (99%)
Eco dyno usage for this app: 0h 0m (0%)
For more information on dyno sleeping and how to upgrade, see:
https://devcenter.heroku.com/articles/dyno-sleeping

=== web (Eco): npm run start (1)
web.1: up 2022/05/02 15:48:33 -0400 (~ 6m ago)

The running web dynos serve requests. Visit the app at the URL generated by its app name. As a handy shortcut, you can open the website with:

$ heroku open

Eco dynos sleep after thirty minutes of inactivity, for example, if they don’t receive traffic. This behavior causes a delay of a few seconds for the first request upon waking. Subsequent requests perform normally. Eco dynos consume from a monthly, account-level quota of eco dyno hours. As long as you haven’t exhausted the quota, your apps can continue to run.

To avoid dyno sleeping, use a Basic or professional dyno type as described in Dyno Types.

Scale the App

Horizontal scaling an application on Heroku is equivalent to changing the number of running dynos.

Scale the number of web dynos to zero:

$ heroku ps:scale web=0

Access the app again by refreshing your browser or running heroku open. You get an error message because your app no longer has any web dynos available to serve requests.

Scale it up again:

$ heroku ps:scale web=1

View Logs

Heroku aggregates all output streams from both your app and the platform’s components into a single channel of time-ordered logs.

View information about your running app using the heroku logs --tail command:

$ heroku logs --tail
2022-05-02T19:57:28.471748+00:00 heroku[router]: at=info method=GET path="/" host=example-lwc-project-1234567890ab.herokuapp.com request_id=67e164cc-fe43-40cb-869d-8843437d8aab fwd="204.14.236.210" dyno=web.1 connect=0ms service=348ms status=200 bytes=916 protocol=https
2022-05-02T19:57:28.618296+00:00 heroku[router]: at=info method=GET path="/1/bundle/esm/l/en-US/bi/0/module/mi/example%2Fapp%2Fv%2F0_0_1/s/dd906b596d93b171095575adf165247650854928/bundle_example_app.js" host=example-lwc-project-1234567890ab.herokuapp.com request_id=fb4212cc-654e-4e10-8512-148999abc9a9 fwd="204.14.236.210" dyno=web.1 connect=0ms service=2ms status=200 bytes=1066 protocol=https

Visit your application in the browser again to generate another log message.

Press CTRL+C to stop streaming logs.

By default, Heroku stores your app’s 1500 most recent log lines. You can provision a logging add-on or implement your own log drain for long-term storage. In the next step, you add a logging add-on to your app.

Provision Add-ons

Add-ons are cloud services that provide additional services for your application, such as databases, logging, and monitoring.

Several logging add-ons are available that provide features such as log persistence, search, and alerting. Papertrail is one such add-on with a free plan.

Provision the Add-on

$ heroku addons:create papertrail
Creating papertrail on example-lwc-project... free
Welcome to Papertrail. Questions and ideas are welcome (technicalsupport@solarwinds.com). Happy logging!
Created papertrail-asymmetrical-88691 as PAPERTRAIL_API_TOKEN
Use heroku addons:docs papertrail to view documentation

This command provisions the add-on and configures it for your application. To see this particular add-on in action, visit your application’s Heroku URL a few times. Each visit generates more log messages, which route to the Papertrail add-on.

You can list all of your app’s active add-ons with this command:

$ heroku addons

View Logs in Papertrail

Visit the Papertrail console to see the log messages:

$ heroku addons:open papertrail

Your browser opens up a Papertrail web console that shows the latest log events. The interface lets you search and set up alerts:

Push Local Changes

In this step, you learn how to propagate a local change to the application through to Heroku.

Open src/modules/example/app/app.html. Change the Hello, World! greeting to say your name instead.

Run heroku local to see your changes locally.

Commit and deploy your local changes to Heroku. Visit the app to see your changes in action:

$ git add .
$ git commit -m "Changed greeting"
$ git push heroku main
$ heroku open

Start a One-off Dyno

The heroku run command lets you run maintenance and administrative tasks on your app in a one-off dyno. It also lets you launch a REPL process attached to your local terminal for experimenting in your app’s environment or your deployed application code:

$ heroku run node --version
v16.15.0

If you receive an error, Error connecting to process, configure your firewall.

Remember to type exit to exit the shell and terminate the dyno.

Next Steps

Congratulations! You now know how to deploy an LWC project, run it locally, scale it, view logs, attach add-ons, and push changes.

Here’s some recommended reading to continue your LWC and Heroku journey:

• How Heroku Works provides a technical overview of the concepts encountered while writing, configuring, deploying, and running apps.
• LWC Developer Guide
• LWC Recipes
• How to Securely Access Salesforce with LWC OSS
• How I Built a Christmas App with Node.js, LWC OSS and Heroku