How to... host a site using Github Pages and Parcel
Aye mate! If you are here, you want to deploy & publish a site using the free hosting offered by Github and Parcel, the latter as the bundler for all the packages/libraries you use in your site 😊
If you're a beginner (as I were some months ago), you may be questioning, why do I need an hosting service and a bundler? Let me answer in the quickest & simplest way I can (click Here to go straight to the point instead).
An hosting service is a service that will actually hosts all the files of your site and expose them for public access. Without this service, you would need to expose those files constantly to the world from your laptop! When you start messing around, it's very nice to have a free and good hosting service that you can use directly from your repository - that's where Github Pages comes in handy.
A bundler is a tool that helps to bundle modules (libraries, a.k.a. reusables pieces of code) you use in your application in files ready to be included in your web pages and to be read by browsers. Many bundlers exist for Javascript but Parcel has the great strength of being really straight-forward and simple to use! At the start of a web development career, you'll want to use libraries, frameworks, without additional overhead for their usage.
Bundlers like Webpack have a steep learning curve, due to its great customization options, and aren't really the best option for newcomers or small sites. Parcel, on the other hand, is simple to use and really good to start working on your skills!
An hosting service is a service that will actually hosts all the files of your site and expose them for public access. Without this service, you would need to expose those files constantly to the world from your laptop! When you start messing around, it's very nice to have a free and good hosting service that you can use directly from your repository - that's where Github Pages comes in handy.
A bundler is a tool that helps to bundle modules (libraries, a.k.a. reusables pieces of code) you use in your application in files ready to be included in your web pages and to be read by browsers. Many bundlers exist for Javascript but Parcel has the great strength of being really straight-forward and simple to use! At the start of a web development career, you'll want to use libraries, frameworks, without additional overhead for their usage.
Bundlers like Webpack have a steep learning curve, due to its great customization options, and aren't really the best option for newcomers or small sites. Parcel, on the other hand, is simple to use and really good to start working on your skills!
Note: When you feel ready, you can start reading more on bundlers from this great source: MDN Package Management! Don't rush it, as it's quite an intermediate topic, but keep in mind to give it a look, it's an important topic to know.In-depth Corner
WYSIWYG: you're about to read a simple guide that uses Parcel to bundle all those libraries and deploy the built pages on the gh-pages branch branch of your Github repo, ready for the world to read it.Requirements
For this tutorial, you'll need to have:
- a Github account (Hello World on Github)
- Nodejs & npm (the Javascript package manager we'll use to install libraries and use parcel)
- Parcel
At this page you can find the code of a basic site that was created with this tutorial. You can check it live at Live Example!
A note: $ identifies code lines in a Shell/Terminal - when you paste the code lines in the shell, leave out the starting $.
You'll find all the instructions and commands inside a
You'll find all the instructions and commands inside a
code
section!In-depth Corner Guide
Okay, let's start assuming you have created your Hello World Site. You've created all the folders for your files, you've got your nice index.html ready and working, with the stylesheets and scripts correctly referenced inside.
You uploaded it on GitHub and it looks neat.
Let's assume you now want to use Bootstrap and JQuery without using a CDN, therefore you'll use a package manager and will create a bundle for your files and libraries 😊.
You uploaded it on GitHub and it looks neat.
Let's assume you now want to use Bootstrap and JQuery without using a CDN, therefore you'll use a package manager and will create a bundle for your files and libraries 😊.
- Install Node.js (that comes with npm) and then proceed to install the libraries you need from the terminal:
$ cd "your_folder_path" $ npm init $ npm i parcel $ npm i bootstrap $ npm i popper.js $ npm i jquery
As you can see, at line 3 I made you install Parcel. You can also install it as a global package by typing$ npm i parcel -g
instead.
If you choose to install it globally, you'll be able to use it on different projects without needing to reinstall it each time. In this case, it's recommended to include parcel as a peer-dependency in your package.json.In-depth Corner - With
npm init
you create a package.json by filling the input provided. Add the following lines to your package.json:"scripts": { "start": "parcel ./*.html", "predeploy": "rm -rf dist && parcel build ./*.html --public-url "paste here your ENTIRE REPO URL, comprehensive of http/https part"", "deploy": "gh-pages -d dist" },
npm run {script_key}
. We'll understand in a second what these lines mean. - At the start of your Javascript entry point you require the libraries:
// index.js import $ from 'jquery' import 'popper.js' import 'bootstrap/dist/css/bootstrap.min.css' import 'bootstrap/dist/js/bootstrap'
// index.js $(document).ready(()=>{ $('body').html('Hello World, if you see this message Parcel Bundler and Github Hosting are working nicely!'); })
$ npm run start
and magic, something happens!Parcel will build and host your files on a local port, thus you'll now be able to browse your site at localhost:{port} (replace port with the one you can read in the terminal). When you open the page you'll find that your site is working!npm run start is the first alias we use, when we call it it will simply run parcel with an argument relative to the entry points of the application.We have our site running fine with all the built libraries and now we want to publish it using Github-Pages Hosting.
./*.html is a glob pattern with a wildcard that stands for: build all the .html extension files you find in the folder from where you run the command. If you have html in sub-folders, you can add other globs to the command like ./{folder}/*.html (Parcel will interpret it as a list of entries to search). In-depth Corner - First thing, in the .gitignore let's add those lines:
// we will ignore node_modules, dist (the output folder you won't track) and the .cache (parcel working folder) node_modules/ dist .cache
Let's create a Github-Pages branch, push to your remote repo and the switch back:$ npm install gh-pages
$ git branch gh-pages $ git checkout gh-pages $ git push origin gh-pages $ git checkout master
- We're back on the main branch, with our gh-pages running (you can check that the page is online in your online repo, by going to Settings. Github should publish it by default when it finds the gh-pages branch. If you need further help check the documentation).
It's now time to review the other two lines of the "scripts" section we added before.In-depth CornerWhat are we doing? We are creating a script for npm that will execute those commands:Pre-Deploy: it will delete the previous dist folder (the folder where are located the processed parcel files) + it will build the site from your entry point. With public-url you set the dns name of your site.Deploy: it will use gh-pages package to re-create the gh-pages branch based on the dist folder and it will "commit&push" it to your remote repo.WARNING!Please Note: if you have a CNAME file, containing the personalized url of your site, you !MUST! substitute the "predeploy" line in the last snippet with:
This instruction will make Parcel build your page on the specified url and it will copy the CPNAME file in the dist folder - this way you'll be able to presist the CNAME and map the custom domain you're using."predeploy": "rm -rf dist && parcel build index.html --public-url "paste here your PERSONAL url, comprehensive of http/https part" && cp CNAME ./dist"
You can apply the same command for every file you need to include in your hosted files. - The job is now easy: you work on your site by running
npm run start
script, that use the Parcel local dev server.Every time you have a new version ready to deploy, you type this command in Terminal:
Parcel will run, build the site and deploy it to GitHub with all the dependencies you used and are needed by your scripts. Fast, easy, good to go!$ npm run deploy
Thanks for reading!
This small guide is a simple start point for your site. I felt interesting to write it because it helps a newcomer to start messing around with web development and, at the same time, I cited and wrote some concepts that a new dev will read as an appetizer, hopefully giving him the curiosity to search more! That's what I did and nowadays still do with articles.
If you have any question, doubt, comment, feel free to write me down below on Disqus, at my mail or to my socials! 😊