15  Projects from degit

As usual, we’ll learn by doing. So let’s jump in with a project.

For this project, we are starting from a template saved in a repo. We’ll use a special npm package called degit to start our project. You should have already installed it globally when we did our computer setup.

As such, we won’t need to create a README or .gitignore file because they will be part of the template. But you will need to create a project folder:

1. Create a new project folder called yourname-sass inside your icj folder.
2. Open that folder in VS Code and open your terminal.
3. In your terminal, run degit utdata/icj-sass-template. This should download all the template files into your folder.
4. Run npm install. This will install all the packages we need from the npm “app store”. It will take a couple of minutes.

Important

When running npm install or when viewing your project on Github, you will see warnings about outdated packages and dependencies. These will not affect our work on this project.

5. Run gulp dev.

When you run gulp dev from your Terminal, a bunch of cool stuff happens. The process creates our “development environment”:

• All HTML and image files are copied from a src directory into the docs directory, which is where our publishable code will live.
• A task compiles all the fancy SCSS files into regular CSS files that your browser can read.
• A program called Browsersync launches a web browser window and displays your web page .
• Browsersync also watches your HTML and SCSS file for any future changes and then reruns tasks and refreshes your browser so you can see your changes.

(Sometimes errors in your SCSS might crash Gulp. Sometimes the error message will help you find and fix the problem, and then you can re-run $ gulp dev.)

15.1 The structure of the project

The template you pulled already as the Node.js development environment defined with a specific (and common) folder structure.

Let’s talk about how the folder system is structured:

15.1.1 src

You will only work with the files in the src folder. There are a series of “tasks” in the development system that will process and move files to the docs folder, which is our “publishable” website.

src
├── img (files will get moved to `docs/img`.)
│   ├── harvey-dale.jpg
├── scss (files here get complied into `docs/css`.)
│   ├── new-styles.css
│   ├── old-styles.css
│   ├── reset.css
├── index.html
├── shows.html

15.1.2 docs

The docs folder is our publishing folder, where our website lives. These are the files that will be published to the web as a working website. Everything outside the docs folder just supports the creation of the files inside docs. DON’T EDIT ANY FILES IN THE docs FOLDER. If you do, the changes will just be overwritten.

Note

We use the docs folder for our publishable code to take advantage of a special feature in Github that will give us free publishing to the Internet. Other common folder names for publishing you might come across are dist and public.

docs (don't edit anything in here)
├── css
│   ├── (files from `src/scss` end up here)
├── img
│   ├── (files from `src/img` end up here)
├── index.html
├── shows.html

15.2 How development environment works

This setup of having a src folder is pretty common in development. We work with the files in the src directory as there are background processes that run on those files, do cool stuff, and then compile the result into our publishing directory, in our case docs/.

The docs folder ends up being the “root” or base level of our site. All other files in the project need to need to be referenced relative to where they end up inside docs.

• Any .html file in src/ gets moved to a similar place in docs/.
• Sass files in the src/scss/ folder get compiled/rewritten into the docs/css/ folder. There are two important implications of this:
  • While the file name you edit ends in .scss, the compiled file in docs/css/ a .css extension.
  • This means your HTML files that end up at the root of docs will need to link to a compiled css file of the same name, but inside the css folder and with a .css extension, like href="css/filename.css".
• Files in the src/img/ folder are moved into docs/img/. Since your index.html file ends up in docs, then your img link needs to be img src="img/filename.jpg".

15.2.1 Configurations files

The remaining files and folders in the root folder are part of the development ecosystem. We don’t mess with this files much in our lessons, but here is a description of what they do:

• .gitignore tells Git which files to ignore sending to Github.
• README.md describes what the repo is about. It has our installation instructions.
• .gulpfile.js is the file that controls our task manager. This is where we tell the Gulp program where to find our Sass SCSS files and then where to place the compiled new CSS files. We won’t edit this file, but know it is necessary.
• The files inside tasks are the workhorse of Gulp. Like the gulpfile, we won’t get into how they work. Just know this is the guts of the development ecosystem.
• package.json is the file that tells the Node.js ecosystem which packages to download from npm. It is pre-configured for you.
• package-lock.json is created by the npm install command based on the package.json file. It contains a bunch of details about dependencies that we don’t need to worry much about. Again, it is created by npm.
• A node_modules folder is generated from package.json when you run $ npm install. It will contain all the mini-programs, and it SHOULD NOT be pushed to Github ’cause it is huge. It’s been excluded in the .gitignore file.