Implement less watch

[brenmcnamara]

For this project, you will implement watching for less changes. The feature works as follows:

From the command line, you should be able to run: babel-node buildScripts/buildLess --watch and start a process that will recompile when less files are added, removed, or changed.

Preliminary

• Make sure to do all the things in the Setup section of the README.md file
• Please add babel-node command globally
  • Run npm install -g babel-cli
  • Check that this worked with which babel-node

The Goal

• The goal is to modify the buildLess.js script to support watching for file changes.
• The script, as of now, will just compile all the less files that are in the directory and quit
• When the --watch flag is provided, instead of quitting, we continue to check for changes in the directory so that we can add / remove less files.
• If a file is changed, we are going to recompile the changed file and overwrite the existing css and css map files
• If a file is added, we are going to compile that file and write the resulting css and map files
• If a file is removed, we are going to delete its corresponding css / css map files

Step 1: Fork this repo

• At the top left of this page, there is a button titled Fork. Forking a repo will create a clone of it in your own set of repositories. You can make changes to your local repo and once you are done making those changes you can request that they be added to the root repo
• Clone the forked repo onto your computer
• Create an upstream remote: git remote add upstream <link to Brendan's copy of repo>
• Create and checkout a branch for the feature you are implementing: git checkout -b less-watch

Step 2: Add a removeFile function

• There is a section at the end of buildLess.js named Utility Functions
• This contains helpful functions that are used by the system
• There are two utility functions listed in the section that do file io operations, readFile and writeFile. They both delegate to the native fs module, but because this module doesn't use promises, they wrap the callback inside a promise and return the promise, which completes when the operations are successful.
• We will need a removeFile function that takes the name of the file to remove and returns a promise which completes when the file has been deleted.
• You will want to use the fs.unlink method to remove the file. Here is an example of how to use it
• Go through the method readFile as an example of how to implement this method. Note that the promise will resolve with no arguments.

Step 3: Setup File Watching

• Currently the script gets a list of files and compiles them. You will want to do that if the watch flag is turned off, but if it is on, you will have to try a different approach
• There is an awesome module named chokidar which makes listening for file changes simple. I have implemented a script in the repo named howToWatch.js that demos how to use chokidar to watch for file changes.
  • run babel-node howToWatch.js from the root of the repo, then make some changes to the less directory to see what prints on the screen
  • make sure to revert any changes you make to the directory

Step 4: Implement recompiling on change and add events

• Note that files that have been changed or added will be handled the same way.
• When chokidar notifies you that a file has been changed / added, you need to do the following:

(1) Output to the console that the name of the file that has changed / added (in blue)
(2) Compile the less file using compileLessAndWriteToCSSFile
(3) If the compilation succeeds, output to the console that compilation was successful and the name of the file (in green)
(4) If the compilation fails, output the name of the file that failed compilation (in red)

Step 5: Implement removing css / css map files on unlink events

(1) Log that a less file was deleted (in blue)
(2) Get the name of the css and css map files that correspond to the deleted file. Do this by using the methods:

• Stylesheets.getDistCSSFileForLessFile(filename)
• Stylesheets.getDistCSSMapFileForLessFile(filename)
  (3) Run the removeFile function you created on both of these files.
  (4) Whether or not the deletion was successful, don't output anything to the console. Just silently succeed / fail.

Step 6: Add npm script

• Next, we need to add an npm script that runs the watch command for us
• In package.json, add an entry under scripts with key: "build-watch:less". The value of that script is the command that will run buildLess with the --watch command

Step 7: Testing

• Please make sure to manually test your feature.
• Run the command babel-node buildScripts.js --watch and make changes to the directory of less files to see if it is behaving as expected
• Make sure the css files and map files are being created / changed / removed: look inside the directory dist/css
• Make sure running the script works: npm run build-watch:less

Step 8: Delete howToWatch.js

• I wrote that to help with this issue, please delete that file. It's no longer needed

Step 9: Submit code

• Commit your changes: `git add . && git commit -m ""
  • IMPORTANT: MAKE SURE TO FOLLOW THE COMMIT MESSAGE CONVENTIONS:
    • Verbs are in present tense
    • at the end of your message, include "-- closes #" where is the number of the issue that this commit is implementing
      • example: git commit -m "Adds watching for less files -- closes Implement less watch #10"
      • once the commit is merged into master, this task is automatically closed if you follow that convention
      • If you make a mistake in your commit message, run git commit --amend to rewrite the message
• Push you changes to your forked copy: git push origin less-watch
• Navigate to the github page for you forked copy. There should be a message that is asking you if you want to create a pull request. Select that message and a pull request should automatically be sent to the upstream copy of the repo
• Once I approve the change, it will get merged in
• Here is a youtube video on how to submit pull requests if you are still confused about it

Edge cases to keep in mind

(1) Adding a directory into the src/less directory. Adding a directory occurs with the addDir event, which you will not ignore.
(2) Adding a file that does not contain the .less extension. This case you can assume will not happen.
(3) Someone saves a less file that has compilation errors. This will happen all the time since as you make changes to less files, it is possible that you make intermediate save on invalid content. In this case, the error should show, but we should not be throwing any errors so that the process can continue running and we can recompile as soon as the less becomes valid.