Using Static Analysis Tooling with Open Source!

Welcome to another blog post about the journey of Octo, the open source tool for static site generation! Today I will be going over how I added static analysis tooling into the project and how you can do the same for your open source projects!

Tools Overview

To start, I am going to go over all the tools that I added to Octo and show you how to add them to your project. I will also be providing links if you want more configuration options or more information on the projects.

Eslint

Eslint is a great tool for checking errors in your code! I would strongly recommend you use eslint in your developer environment and all projects you work on. I have been using eslint as my linter for a few year now with all my code and it has helped me keep my code in good shape. To add eslint to your project run npm install eslint --save-dev. Now that eslint is in your dev dependencies, you can run npx eslint --init. This will prompt you to create a config file that works for your project. If you now run npx eslint . eslint will check all the files in your project for errors!

Octo's .eslintrc.json looks like this:

{
  "env": {
    "browser": false,
    "node": true,
    "es2021": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 13,
    "sourceType": "module"
  },
  "rules": {}
}

I set "browser" : false and "node": true because my project is a tool that uses node and doesn't use the browser to operate.

Prettier

Prettier is a code formatter that supports a ton of languages including javascript! We are using this as it helps make our code readable and it allows us to enjoy one style of coding!

To install Prettier run:

• npm install --save-dev --save-exact prettier
• echo {}> .prettierrc.json to create an empty config file.
• echo >> .prettierignore to creat a ignore file exactly like gitignore.

Octo's .prettierrc.json is currently empty because the current formatting for me is good. The .prettierignore is just a copy of our .gitignore so for your project you can do the same!

Now prettier should be in your project! To use prettier run:

• npx prettier --write . to format and save all your files.
• npx prettier --check . to see if your project is formatted.

Writing NPM Commands

Now that we have our two first awesome tools, we should write some scripts so we aren't constantly writing multiple commands at once! head over to your package.json in your preferred text editor and look for the scripts section. It should look like this:

"scripts": {
    "start": "node ./bin/app.js"
  },

Once we are there we can start writing some scripts to help us reduce the amount of commands we are writing. To start lets write a basic test script.

"scripts": {
    "start": "node ./bin/app.js",
    "test": "prettier --check && npx eslint ."
  },

The "test" part of the command can be named anything you like but should be related to what it runs. Our test command runs prettier --check to check if all files are formatted. We then use && npx eslint . to use eslint to check our project. If we now run npm run test it will run both commands with a single line! Now lets go to the next level!

"scripts": {
    "start": "node ./bin/app.js",
    "test": "npm run prettier-check && npm run eslint",
    "eslint": "npx eslint .",
    "prettier-check": "prettier --check ."
  }

Now that we know how to write one command, why not use those commands with other commands. With this script we wrote two new commands eslint and prettier-check. eslint runs eslint check and prettier-check checks the files to make sure they're formatted! Now we can call those commands in the test command using npm run. You can also use the commands separately now if you don't want to run both at the same time.

As you can see, you can get very creative with it as you can see with Octo's scripts:

"scripts": {
    "prepare": "husky install",
    "start": "node ./bin/app.js",
    "build": "npm run prettier && npm run eslint-fix && npm run eslint",
    "test": "npm run prettier-check && npm run eslint",
    "eslint": "npx eslint .",
    "eslint-fix": "eslint --fix .",
    "prettier": "prettier --write .",
    "prettier-check": "prettier --check ."
  }

Husky

Wow that is a lot of information about two tools! Now how cool would it be if your project would automatically run these tools whenever you made a push or commit? Well here comes Git hooks to the rescue with the power of Husky! To install husky run npm install husky -D. That doesn't fully install husky, to fully install it we have to run another command. Since we just learned about writing scripts in our package, we should write a new one for preparing our project.

"scripts": {
    "prepare": "husky install",
    "start": "node ./bin/app.js",
    "test": "npm run prettier-check && npm run eslint",
    "eslint": "npx eslint .",
    "prettier-check": "prettier --check ."
  }

Now that we have husky install as a command, we can run npm run prepare to get husky fully installed. It should have a generated .husky folder in the root of your project. Now lets write our first hook!

Run this command to create a pre-commit script for husky:

npx husky add .husky/pre-commit "npm test"

This command creates a file within the .husky folder and names it pre-commit. It sets the command npm test to run every single time you commit within the project.

Customize your Developer Environment!

Now that we have our cool customized developer environment for our project, we want to make sure people working on our project are using the tools we utilized today. To do that we need to create .vscode folder with our rules. This part is easy depending on how much rules you want to add to your project. To start you should create a folder called .vscode and within it create two files named settings.json and extensions.json.

Settings

{
  "editor.formatOnSave": true,
  "files.autoSave": "afterDelay",
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnPaste": true,
  "editor.inlineSuggest.enabled": true
}

These are Octo's rules. These rules are inherited from my personal profile. The rule that is very important here is "editor.defaultFormatter": "esbenp.prettier-vscode". This makes sure that when someone is working in your project that they're using prettier as the default formatter. The other lines in the file are about auto formatting so if you forget to save often like me you might want to use them! If you want to use your own settings on VS Code you can open command palette and type settings.json. It should give you options on which settings you would like to open. You can then copy that into your settings.json within the .vscode folder we created earlier.

Extensions

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "streetsidesoftware.code-spell-checker"
  ]
}

This is Octo's recommendations for extensions. Whenever someone opens your project in VS Code it will ask them to download the recommended extensions for the project. One extension I didn't talk about was code-spell-checker. This extension is great for checking for spelling errors within your code.

Extra Information

If you enjoy these extensions you can download them through the extensions tab on VS Code. I have used these tools in my personal developer setup for an extremely long time and they have helped me a ton. I used them on Octo before I went to an automatic setup so the tools didn't find any problems yet. Having them installed doesn't hurt and will only help you!

Conclusion

Now you have an awesome project that uses tools to automatically make sure whoever is working on your project is following your rules! If you want to contribute to Octo you can here. If you have recommendations for other tools or want to share your developer setups, I would love to read them in the comments! Thanks for reading!