(bright upbeat music)
- Hi, everyone my name is Aditya
and I'm a developer evangelist at Salesforce.
In this Quick Take,
I'm going to show you how you can deploy
and host your Lightning Web Components Open Source apps
on GitHub Pages.
In case you're wondering how to create the app
in the first place,
then check out my previous Quick Take linked
in the description below.
Let's get started.
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,
basically anything that's static,
and can be rendered on the client side.
So that means you can't run server side logic
like Node JS scripts 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 gh-pages branch
or the docs folder on any branch.
Where you store the files is totally up to you,
but the first step is to generate these static files
for our Lightning Web Components Open Source app.
Let's see how that is done.
Here we are in our LWC OSS app.
And let's go to package.json
Let's scroll down to the "scripts" section.
And here you'll 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.
And this production build process is the one
that generates the static files for us.
Let's run the script.
Once the script is run,
you can see a new folder with the name "dist" is created,
which contains all the transpiled files.
So here you have the HTML file and two JavaScript files.
All your web components, the LWC engine,
third party libraries you used are bundled into
these JavaScript files.
The "resources" folder holds your images and icons.
These are the files that you can then host
and run your app on any platform.
If you are deploying this to a PaaS application like Heroku,
you would also need to use
the serve script in package.json,
which essentially creates a simple Express server
to serve this build output.
But since GitHub Pages itself is a hosting service
that can serve static content by itself,
it doesn't need this Express server.
So we won't be needing the serve script here.
So now we have our files ready.
The transpiled files are present
in the dist (distribution) directory.
And the source files are pretty much everything else.
You can just push your transpiled files to GitHub.
Or if you really want to open source your project,
you can push both the source files and the transpiled files.
Here are a couple of options you have. The first one,
you can push your transpiled files
to the root of the main branch,
you would typically use this
to let's say create your personal website or create a blog,
or pretty much any site that you want to host using LWC OSS
you would generally prefer this method.
The second and third options can be really useful
if you want to open source your projects
that means both source files & transpiled files go on GitHub
In the second option, you push all of your source files
on to the root of the main branch,
and your transpiled files to the
root of the gh-pages branch.
The third option is to push both your source files
and the transpiled files to the same branch: main.
But then the transpiled files go into the docs folder.
So these are only some of the options
you have various permutations and combinations
that you want to use based on what you're trying to do.
But as I mentioned earlier GitHub Pages
can serve content from the root of the main branch,
or the root of the gh-pages(GitHub Pages) branch,
which is what options one and two are doing.
And it can serve out the files
from the docs folder on any branch,
which is what the third option is doing.
Let's look at some of these in action.
First, let's create a GitHub repo.
Make sure it is public.
Because if you want to create GitHub Pages
on private repos,
you need to upgrade to the pro plan on GitHub.
You need not add any of these
and just create the repository.
Here are the list of commands that you need
to execute in order to push your code to GitHub.
Let's run them.
So because we want to push the contents only
of the dist (distribution) directory,
let's move to the directory.
Now, let's execute these commands.
git init, and then git add. to add all the files.
git commit to commit all of this code to the repo.
Then add the Git remote URL as the origin
and finally push the code.
Now we go back and refresh this page.
And you can see that your code
from the dist(distribution) folder is now pushed
into the main branch.
And now to enable GitHub Pages,
go to Settings.
And scroll down to the GitHub Pages section.
So here you can see it asks you to choose the source.
Let's choose the main branch.
And we say it's the root of the main branch.
And then let's click Save.
And this begins your deployment process.
And in just a while you'll see that your GitHub Pages
has been successfully deployed,
you can just click the link here
and see the LWC app in action.
And you can also verify that
it has been served from github.io
which is what GitHub Pages uses
to serve out web pages.
Now, this is the process if you would want
to deploy apps,
and you don't want to share the source code
with everyone else.
But what if you want to share the source code as well.
As I mentioned earlier you have two options.
One is that you can push your source code
to the main branch,
and then the transpiled files can go
into the gh-pages(GitHub Pages) branch.
Or you would want to push both of them
to a single branch: main
and have the transpiled files in the docs folder.
The approach is up to you.
But in this Quick Take
let's look at the docs folder approach,
because I want to show you a few things.
So let's go back to our repository.
In the folder structure,
you can see we have all of our source files
and the dist (distribution) folder.
But now we need our transpiled files
to be in a folder that is called docs.
So one thing we can do is of course,
once you have run your build command,
just rename this dist to docs and you can deploy it.
But there is a more elegant way of doing it.
If we go and look at package.json
what you can see
is 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 list by clicking
this link over here.
What you can see here is a list
of all the settings that you can pass
to lwc-services, most importantly,
the build directory.
So let's copy that and paste it
into our lwc-services config.
And what we need to do here is rename dist to docs.
And if you look at resources,
they're going to go from src/resources
to dist/resources,
we need to rename this also to docs.
And now save it.
Let's run the build script now.
And what you can see now is a creates a folder
with the name docs.
If you expand that, you can see
all of the same contents.
So now all you need to do is push
all of this folder to a new GitHub repository.
Because the previous one that we have created,
we've already pushed code to it.
So let's create a new repo.
And then push the source files and the docs folder to it.
I'm going to name it a little bit differently
by appending docs to the name
and leave the same settings as before,
and just create the repo.
And now as usual follow all of these steps.
And this time, we are going to be running those
on the project folder itself and not the docs folder.
Because we need both the source files
and the docs folder to be deployed.
I have now deployed the code.
And we can refresh this page to look at the output.
So here you can see that all the source files
have been committed along with the docs folder,
which contains the transpiled files.
Now we follow the same process to enable GitHub Pages.
But this time, we're going to choose the docs folder.
And save.
And that's it.
That's all the information you need
to deploy to GitHub Pages.
So what's next,
you can actually automate the process
of running the build script and committing the resultant
transpiled files to either the branch
or the folder using GitHub actions,
pre commit hooks or the gh-pages library.
And that's about it for this Quick Take.
Thank you for watching.
If you have learned something,
be sure to like this video.
If you want to get more content
like this pushed directly to you.
Click Subscribe and click that bell icon
to get notifications.