21  Codespaces projects

21.1 Creating your project

Important

This chapter is being rewritten to utilize Github Codespaces as the primary development platform, which is a recent change. Please bring to my attention anything that doesn’t make sense.

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

Instead of first creating a folder on our computer to store all our code, we’ll make a copy of an existing Github repository, and then work from a virtual computer attached to that repo.

  1. Go to the icj-sass-template repo.
  2. Click on the green Use this template button and choose Create a new repository.
    • This should allow you to create new repo based on icj-sass-template. Call this new repo yourname-sass.
    • Leave all the other settings the same and click Create repository.
    • It takes several seconds to create your repo.
  3. Click on the green <> Code button and then choose the Codespaces tab.
    • Click Create codespace on main.
    • This will take a bit more time, but should just be a couple of minutes. **It will pause at one point and give you a prompt, but wait until you see it say “Detected Node.js” and let it finish that setup.
    • Once the Node installation finishes, your browser will look like you have a version of Visual Studio Code open, and you do!

A virtual machine will be created and you’ll see the name in the folder listing, and again at the very bottom left of your browser. It’s usually a word mashup like glorious winner. You’ll want to continue to use this same virtual codespace as you work on this project.

We need to install a piece of software onto this new virtual machine, and we might as well do it now so we don’t forget. I’ll explain more about npm and gulp below.

  1. In the codespace’s VS Code Terminal, run:

    npm install -g gulp

  2. In the Terminal, 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.
If you get an error after running gulp dev …

There is a base command the virtual machine is supposed to run when it launches to install all the node packages. If you run gulp dev and it say it can’t find packags, you might need to run npm install first, and then try gulp dev again.

When npm install does run you will see warnings about outdated packages and dependencies. These will not affect our work on this project. You can ignore them.

One last thing here … Sometimes when you are writing your SCSS code it might crash Gulp. You can read the error message for help finding and fixing the problem, and then you can re-run $ gulp dev.

21.2 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:

21.2.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

21.2.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

21.3 How a development environment works

This setup of having a src folder is pretty common in software 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".

21.3.1 Configurations files

The remaining files and folders in the root folder are part of the development ecosystem. We don’t mess with these 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.