Building for keeps

At some point we’re going to want to build a production copy of our files - something we’re willing to publish to the internet! To do this, we can start with just a simple command to tell parcel to build the website instead of building and serving it.

parcel build index.html

It’s the exact same thing parcel did before - saving into the dist/ folder - except if we peek at our finished graph file - graph.185b2ef5.js or whatever - you’ll see it very very different.

It’s all mashed together on one line, it’s totally unreadable, it’s definitely not lint-friendly - it’s bundled and minified! Parcel only minifies your code once you’re ready to publish, since otherwise it would be pretty hard to debug it.

Since we’re probably going to publish to GitHub pages, I’m going to make a checklist of needs before we publish:

• Our finished code has to go into a docs/ folder
• Our finished code has to point to the correct GitHub subdirectory
• Parcel needs to support multiple html files in multiple folders with multiple js files
• We don’t want the dist/ stuff to go up on GitHub

Publishing into docs

First, we can change our parcel build to do output into docs/

parcel build --out-dir docs index.html

Pointing to the right subdirectory

If we look at our index.html file and take a look at our script tag, it looks something like this:

<script src="/graph.185b2ef5.js"></script>

When we finally publish to somewhere like https://littlecolumns.github.io/d3-project/, this is going to cause terrible problems. The little / at the beginning of the URL changes everything:

So the last one is what we really want, so we need to

parcel build index.html --out-dir docs --public-url /d3-project

Working with multiple files

And if we added in another folder - for example, pizza/ - and put some files in there - for example, an index.html and some JavaScript in there, we can easily tell Parcel to process them, too.

parcel build index.html  pizza/index.html --out-dir docs --public-url /d3-project

But listing all of our HTML files gets tedious and boring! The normal way of doing things is to move all of our html and JavaScript into a folder called src/ and tell Parcel to build everything inside.

parcel build src/*.html src/**/*.html --out-dir docs --public-url /d3-project

Let’s break the command down:

• parcel build - don’t keep watching and rebuilding, just build it once for a ‘production’ build
• --out-dir docs - put the output in docs
• src/*.html - process any html files inside of src
• src/**/*.html - also process any html files inside of any folder inside of src

Note: We don’t need to tell parcel about the .js files because it can find them by reading the HTML!

Hiding some files

When we publish our code, we really don’t care about that dist/ folder. It’s just the folder Parcel stores drafts in while while we’re developing our code, so it makes sense to not send it up to GitHub. We want the original src/ code and the publishable docs/ code, just not the dist/ version!

Also, what about node_modules? We don’t need that, either. Those modules are all listed in package.json, so if someone wanted to download our project and recreate it they can just use npm install to automatically install them all.

When you want to ignore files with git, you create a filed named .gitignore. Yes, it starts with a period, it’s a secret magic file!

.gitignore is just a plain list of files or file patterns to not store in git. You can write it yourself, or you can use something like https://www.gitignore.io/ to find one someone else has already written.

Let’s say we use gitignore.io, search for node, and use what comes up. We can also add the dist directory, and .DS_Store, which is a weird file that shows up everything on OS X. Our final .gitignore might look like this:

# Custom files
.DS_Store
dist

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# parcel-bundler cache
.cache

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Optional npm cache directory
.npm

# dotenv environment variables file
.env

# Optional eslint cache
.eslintcache

# Dependency directories
node_modules/

Now it’s time to send it all up!

1. Make a repo
2. Add our files
3. Make a commit
4. Send it all up
5. Publish through the Settings page on GitHub
6. Rejoice!

Looking to the future

…but let’s say we wanted to make another project. Do we have to do all of that again? NOPE!

If we want to be smart/lazy, we can re-use a lot of the files we already have. These ones will be the same for every project we have:

• .eslintrc for the linting options
• package.json for the dependencies - the packages our project needs (like eslint and Prettier)
• .gitignore for what we don’t want going into git

…and that’s it! We might need to change some of the package.json options, but it’s easy enough in a text editor. It might be worh saving this as a “quickstart” setup! We’d copy them to a folder, run npm install to automatically install everything from package.json, and be good to go!