Netlify Parcel Build
Setup Build
Now that we're moving beyond plain-old HTML and CSS, we need to "build" our projects. In this tutorial we'll setup our project to a Node.js project that is built with Parcel. We'll no longer serve our assets directly on Netlify, we'll serve compiled assets.
First, let's move our public
directory to be our src
directory. From the command line, try running the following move command in bash
:
mv public src
In VSCode you should see your public
folder renamed to src
.
.gitignore - Ignore generated files
In our git
project repository it's generally a best practice to only store source files and not generated files. The easiest way to ignore files in git
project commits is to setup a base file named .gitignore
and list one ignored files/pattern per line. In VSCode, right click outside of the public folder in the File Explorer pane and select "New File". Name it .gitignore
(you should be able to collapse the public directory and still see the .gitignore
file).
Add the following lines to .gitignore
:
node_modules/**
dist/**
.cache/**
Save your file. It will be included in the next git commit.
package.json
file with npm init
Initialize your project's In the terminal, be sure you are in your travel notes directory (try pwd
to print your working directory). Then run npm init
. You can press enter for each of the prompts to accept default settings. Doing this will generate a package.json
file in the root directory of your project. This file is important to node.js
as you'll soon see. Think of it as a description of your project, its dependent libraries, and any special commands your project needs.
parcel
development libraries
Install We're using parcel-bundler
to serve as our project build tool. Add it to your project's development dependencies (meaning, it's only needed when you are developing your project it is not needed in production) with the following command:
$ npm install --save-dev parcel-bundler
Now, if you look in package.json
, you'll notice parcel-bundler
was added to the devDependencies
part of the file along with its current version. You'll also notice this looks like JavaScript object and array literals! This is JSON, or JavaScript Object Notation, a common format for expressing and exchanging information between programs made popular by JavaScript's rise.
Test a project build
You should now be able to build your project using parcel
and the following command:
$ parcel build src/*.html
If there are errors in this command you will need to resolve them before continuing. When it parses and builds HTML it will check for correct closing tags, and so on, to be sure you have valid HTML.
Once you can run the above command without errors, you should now see a dist/
directory that has your project's compiled assets.
npm
commands
Adding In the package.json
file, you will see a top-level property named "scripts"
, whose value is another object where keys are the name of a script and values are the actual command-line operation being executed when that script is run. By default there is a test script with an error. Let's remove the "test"
script add a few useful scripts when working with a parcel
project:
"scripts": {
"start": "parcel src/*.html --open",
"build": "parcel build src/*.html"
},
Now, after adding these scripts to your package.json
file, you can run the following commands:
$ npm run build
The build
script builds the project in the dist
directory. Soon we'll configure Netlify to run this command every time you push your project.
$ npm run start
The start script is configured to run parcel src/*.html --open
which starts parcel
and targets each of your html
pages. To view your index.html
file, you'll need to specifically open localhost:[port]/index.html
.
To quit your server, back in the terminal, press Ctrl+C.
Netlify Configuration
Currently your Netlify site serves assets directly out of your projects (former) public directory. Now, when Netlify deploys your site we first want it to run npm run build
, then we want it to serve your site out of the dist
directory. We can make these configuration changes in our project by adding a configuration file named netlify.toml
. Add a new file to the base directory of your project named netlify.toml
and add the following configuration rules:
[build]
# Root of package.json, etc
base = "./"
# The command to run production build
command = "npm run build"
# Publish directory
publish = "dist/"
Once you've added this, go ahead and make a commit and push to test your deploy settings on Netlify.
$ git add .
$ git commit -m 'Add parcel build pipeline and update netlify to use build.'
$ git push origin master
If you open Netlify, go to your project, you should see your latest commit show up in the production deploys list either in the process of building, built with success or an an error. If you click on the deploy and scroll down you'll see the log of steps the build took. Somewhere in there you should see parcel-bundler
being installed followed by npm run build
later on. This is a log of the steps Netlify is taking to prepare your commit for a production deploy by building it with parcel
. If it does not succeed, check over the steps above and see if you can diagnose the reason why based on error messages.
If you visit your blog site it should still work. If you inspect your HTML using Chrome's web inspector tool, though, you'll see that the link tags link to compiled and minified CSS files for production. Parcel built these files, copied, and updated your HTML into the dist
directory which Netlify is now using. If you open the CSS file you'll see it's "minified" with extraneous whitespace removed to reduce its filesize.
If you're this far, great! That means we've got Netlify configured to build our process and Parcel is successfully building it. The last thing we'll do is ensure we can start using TypeScript with our blog project.
Adding TypeScript
As we add interactive features to our website we need to use JavaScript or another language that compiles to JavaScript. We'll choose TypeScript, which is the latter. To add it to our project, let's add it:
$ npm install --save-dev typescript
This installs TypeScript as a development dependency.
Then, create a file named main.ts
in your src
folder. Establish a main
function such as:
export let main = () => {
let message: string = "Hello world, from TypeScript :)";
console.log(message);
};
window.addEventListener("load", main);
Next, from at least your index.html
file, add a script
tag to include your main.ts
file before the close of its body
tag:
<script src="./main.ts"></script>
Finally, from the command line start your development server again: npm run start
You should be able to browse to the .html
page(s) you added the script
tag(s) to and see that your TypeScript is running (compiled as JavaScript) based on the message logged. If you do not see a logged message you will need to carefully check the steps above again.
Once you see your message logged, stop your development server in console with Ctrl+C.
Now, let's test our build process on netlify by making another commit, pushing, and checking the deploy log:
$ git add .
$ git commit -m 'Add TypeScript support to project.'
$ git push origin master
Shortly after you should see a deploy on Netlify show up. If you follow through your deploy log for this commit you'll see in the list of built assets after npm run build
that the main.<hash>.js
file was compiled from your TypeScript code.
If you now view your site's source code through the web inspector tool and find the script
tag just before body
's closing tag, you should see a reference to the compiled js
file. If you open it, you'll see it's minified JavaScript and buried in the mess (if you Control+F) is your 'console.log' statement compiled to JS. (You may notice that the optimizer even removed your local variable!)
Summary
Once you've made it this far, congratulations! You've established a build pipeline for a modern TypeScript project using Parcel! In any project build pipeline there are a lot of moving parts. Parcel actually simplifies our lives quite a bit compared to more configurable tools like WebPack which achieve similar results through even more configuration and steps.
The upside to this is our code assets, including HTML if you view your page's source code, are all minified with whitespace removed. Additionally, we are able to program in TypeScript and have it compile on deploy to minified JavaScript.