Linters

Usage (For Developers)

This assumes that linting has already been set up for your project.

1. Run npm install in every directory of the project (backend and frontend).
2. Write code as usual and stage your changes.
3. Try to make a commit. The secret scan and lint check should run automatically.
4. Follow the prompts to address any recommendations or warnings.
5. If you're in a hurry, use NO_LINT=1 git commit to skip the lint check entirely.

Initial Setup

.gitignore

Initialize your repository's .gitignore with the Node.js template from github/gitignore:

1. cd into your project's root directory.

2. Download the template:

   curl -o .gitignore https://raw.githubusercontent.com/TritonSE/linters/main/.gitignore

.vscode/settings.json

A VSCode settings file is strongly recommended to ensure that everyone has the same editor and formatting settings in VSCode. Editor settings can mess with ESLint and Prettier and are usually very hard to debug.

• Create a .vscode directory in your project's root directory.
• Create a settings.json file inside it.
• Copy the contents of .vscode/settings.json into your settings.json file.

Note: different settings can also be applied to the backend and frontend by placing a .vscode/settings.json file in each of those directories instead of the root directory. This should not be necessary for most projects.

ESLint and Prettier

For Node.js Backends

1. cd into your backend directory.

2. Install necessary packages:

   npm install --save-dev eslint prettier @antfu/eslint-config

3. Download some config files from this repository:

   for file in .prettierignore prettier.config.mjs backend.eslint.config.mjs; do curl -O https://raw.githubusercontent.com/TritonSE/linters/main/$file; done

4. Rename backend.eslint.config.mjs to eslint.config.mjs.

5. If your frontend is in a subdirectory of the backend, you'll need to add "frontend/" to the ignores array in the eslint.config.mjs file (replace frontend with the name of your frontend directory) to ensure that the frontend and backend are linted separately.

6. Add these scripts to your package.json:

   npm pkg set scripts.check-git-hooks="echo Git hooks not configured yet. You SHOULD NOT see this message unless you are still setting up linting."
   npm pkg set scripts.format="npm run check-git-hooks && prettier --write ."
   npm pkg set scripts.lint-fix="npm run check-git-hooks && (eslint --fix --cache --report-unused-disable-directives . || true) && prettier --write ."
   npm pkg set scripts.lint-check="npm run check-git-hooks && eslint --cache --report-unused-disable-directives . && prettier --check ."

   npm run format reformats your code without doing any linting. npm run lint-fix automatically fixes some lint errors and reformats the code. npm run lint-check doesn't modify any files, and exits non-zero if there are any lint errors or code style discrepancies; this is intended for a Git pre-commit hook or a CI/CD check.

   Ideally, instead of (eslint ... || true) && prettier ..., we would use eslint ... ; prettier .... However, there are some issues with using the semicolon as a command separator in Git Bash on Windows. See this article for more details.

   At a later step in the setup, we'll change npm run check-git-hooks to actually check that Git hooks are installed. This will enforce that every developer has Git hooks installed (at least, every developer that tries to use one of the linting commands).

   Running npm install or npm run prepare doesn't actually guarantee that the hooks are installed, because Husky will skip hook installation if Git is not available on the command line (e.g. for GitHub Desktop users). But these commands also need to run in production environments, which might not have Git installed, so we can't do the hook check there. Thus, we only do the hook check as part of the linting commands, which should never be run in production.

7. Try it out:

   npm run lint-fix

8. Stage and commit the modified files.

For Next.js Frontends

1. cd into your frontend directory.

2. Install necessary dependencies

   npm install --save-dev eslint prettier @antfu/eslint-config

3. If you already set up ESLint when you created the project, you should have a eslint.config.mjs, in which case, you should replace the contents of that file with this file. If you don't have an eslint.config.mjs file, download this file and rename it to eslint.config.mjs.

4. Download some config files from this repository:

   for file in .prettierignore prettier.config.mjs; do curl -O https://raw.githubusercontent.com/TritonSE/linters/main/$file; done

5. Add these scripts to your package.json:

   npm pkg set scripts.check-git-hooks="echo Git hooks not configured yet. You SHOULD NOT see this message unless you are still setting up linting."
   npm pkg set scripts.format="npm run check-git-hooks && prettier --write ."
   npm pkg set scripts.lint-fix="npm run check-git-hooks && (eslint --fix --cache --report-unused-disable-directives . || true) && prettier --write ."
   npm pkg set scripts.lint-check="npm run check-git-hooks && eslint --cache --report-unused-disable-directives . && prettier --check ."

6. Try it out:

   npm run lint-fix

7. Stage and commit the modified files.

For Vite Frontends with React

1. cd into your frontend directory.

2. Download some config files from this repository:

   for file in .prettierignore prettier.config.mjs vite.eslint.config.mjs; do curl -O https://raw.githubusercontent.com/TritonSE/linters/main/$file; done

3. Rename vite.eslint.config.mjs to eslint.config.mjs.

4. Install the necessary packages:

   npm install --save-dev eslint prettier @antfu/eslint-config

5. Add these scripts to your package.json:

   npm pkg set scripts.check-git-hooks="echo Git hooks not configured yet. You SHOULD NOT see this message unless you are still setting up linting."
   npm pkg set scripts.format="npm run check-git-hooks && prettier --write ."
   npm pkg set scripts.lint-fix="npm run check-git-hooks && (eslint --fix --cache --report-unused-disable-directives . || true) && prettier --write ."
   npm pkg set scripts.lint-check="npm run check-git-hooks && eslint --cache --report-unused-disable-directives . && prettier --check ."

6. Remove the predefined lint script to avoid confusion:

   npm pkg delete scripts.lint

7. Try it out:

   npm run lint-fix

8. Stage and commit the modified files.

Git Hooks and Secret Scanning

1. cd into your project's root directory.

2. Download the necessary files from this repo:

   for file in .husky/lint-config.sh .husky/pre-commit .husky/pre-push .secret-scan/.gitignore .secret-scan/secret-scan-config.json .secret-scan/secret-scan.js; do curl --create-dirs -o $file https://raw.githubusercontent.com/TritonSE/linters/main/$file; done

3. Open .husky/lint-config.sh in your editor of choice, and edit the node_dirs variable (if needed) to match your project's frontend and backend directories.

4. Add execute permissions to the pre-commit and pre-push scripts:

   chmod u+x .husky/pre-commit .husky/pre-push

5. cd into the backend and install husky:

   npm install --save-dev husky
   
   # If necessary, change ".." in both commands to refer to the repository's root directory.
   npm pkg set scripts.prepare="cd .. && husky"
   npm pkg set scripts.check-git-hooks="cd .. && node .secret-scan/secret-scan.js -- --check-git-hooks"
   
   # Install Git hooks.
   npm run prepare
   
   # Check that Git hooks were installed successfully.
   npm run check-git-hooks

6. Repeat the steps above for the frontend.

7. Stage the .husky and .secret-scan directories, along with your package.json and package-lock.json for the backend and frontend.

8. Verify that the pre-commit script runs when you commit:

   git commit

9. Verify that the pre-push script runs when you push:

   git push

10. Create a file called fake-env somewhere in your repository, and paste the following text into it:

    mongodb://this-is-a-fake-database
    

    If you run git commit, you should see an error like SECRET DETECTED in working tree, file "fake-env". This secret scanning tool aims to prevent credentials or other secrets from being committed to Git by accident. After deleting fake-env, you should be able to commit again.

    To customize what kinds of secrets are detected, especially if you will use credentials for something other than MongoDB or Firebase, see .secret-scan/secret-scan-config.json in your repository.

11. Ask anyone else who has already cloned the repository to run npm install in the frontend and backend again, so that the Git hooks are installed for them as well.

CI Configuration

Please refer to the sample workflow for GitHub Actions. You'll need to change the directory names for the frontend and backend if they're different for your project.

Development

ESLint and Prettier Configs

Fulcrum and the TSE website can be used to test config changes for Node.js backends and Next.js frontends respectively.

Secret Scanner

The secret scanner aims to prevent secrets (like database credentials or API keys) from being committed to project repositories. It does this by scanning the working tree, Git index, and commit history before code is committed or pushed.

To avoid scanning the entire commit history every time, we also maintain a cache to record which commits contain no secrets.

Secret Scanner Development

To support detection of new kinds of secrets, add regexes to the default config here. The source code for the scanner script is here.

Secret Scanner Testing

To run the automated tests:

secret-scan-tests/run-all-tests.sh

The tests check whether secrets are correctly detected in different scenarios. You should add tests for any new regexes you add, and you should rerun the tests after modifying the config or scanner script.