How to Host LWC OSS Apps on Github Pages | Salesforce Developer Guide

Introduction

GitHub Pages is a static site hosting service that takes files straight from your GitHub Repo to create a website. These files include HTML, JS, CSS, images, anything that's static and can be rendered on the client-side So, you can't run server-side logic like Node JS script or PHP with Github Pages.

There are three places from which GitHub Pages can pick static files to serve out websites.

The Root of the main branch or the GitHub-pages branch or the docs folder on any branch. Where you want to store your files is totally up to you. The first step is to generate static files for our lightning Web components Open Source App.

Open your LWC OSS App in Vs Code Editor and go to the package.json file and scroll down to the script section and here you will find the build script. this is the one that creates a production build based on the bundler you've chosen during project creation. It can be either Webpack or Rollup. This production build process is the one that generates static files for us.

To run the build script click on it and press the Run Script, Once the script is run, it creates a folder named "dist"  which contains all the transpiled files, like index.html and two javascript files, and a subfolder named "resources" it contains images and icons.

These are the files that you can then host and run your app on any platform.

You can just push your transpiled files to GitHub OR if you want to open source your project, you can push both the source files and the transpiled files.

To push your files on GitHub, first, you need to create a GitHub Repo. Once Repo is created it shows a list of commands to execute in order to push your code to GitHub.

If you want to push the contents only of the dist(distribution) directory, 

To move your directory type, cd disc in the terminal that executes the commands given in the Repo.   

Don't forget to check out: Salesforce Platform API Versions 21.0 thru 30.0

Here is The List of Commands

cd dist, git init, git add ., git commit -m "your comment" after that add the git remote URL as the origin and at last push the code to GitHub git push.

Now go back to GitHub and refresh the page and you can see that your code from the dist(distribution) folder is pushed into the main branch.

Now, to enable GitHub pages go to settings scroll down to the pages sections. It asks you to choose the source. Choose the main branch as a source and save it. After refreshing the page you can see your GitHub pages successfully deployed and it will generate a URL. Just click on it and you will see the output of your App in the browser.

Above is the  Process if you don't want to share your source code with anyone else but what if you want to share your source code with everyone.

You have two options: one is that you can push your source code to the main branch and the transpiled files can go into the gh-pages (GitHub Pages) branch. Or you would push both of them to a single branch: main and have the transpiled files in the docs folder.

Let’s take a look at the docs folder approach.

Go back to the Vscode, now we need our transpiled files in a folder called docs. One thing is we  rename the dist folder to docs or go to the package.json file where you can see the build script leverages lwc-services and lwc-services has a config file that lets you configure a bunch of stuff

Ranging from the port number on which the development server runs, the build directory, resources, and much more.

You can find all of that by clicking on the link given in lwc-services.config.js files.

You can see here is a list of all the settings you can pass to lwc-services, most importantly, the build directory copy that and paste it into the lwc-services config and rename dist to docs all over.

After that Run the build script in the package.json file and you can see that it creates a folder named docs with the same content as the dist folder.

Now push all of this folder into the new GitHub Repository. Create a new Repo and push source files and docs folder to it.

Check out another amazing blog by Anuj here: Debunking the Big 5 Myths about Salesforce Marketing Cloud

To push the code into the repository repeat the process as earlier we used.

Here you can see all the source files have been committed along with the docs folder which contains the transpiled files and follows the same process to enable GitHub pages as we used above but this time you have to choose the docs folder instead of root and save it.