jsite-utils

Template Repository

Contents

Name	Purpose
.eslintrc.json	ESLint configuration
.gitignore	Git ignore
.npmignore	NPM ignore
package.json	NPM package
tsconfig.json	TypeScript configuration
node.js.yml	GitHub Action: test on commit/pull request
npm-publish.yml	GitHub Action: NPM & GitHub publish on release
clean.ts	Utility to selectively clean /dist/src/
/lib/	Helpers often used in my projects
/interfaces/	Interfaces often used in my projects

Configuration Files

ESLint

ESLint configuration is used to maintain code quality, readability, and uniformity - across browser-based JavaScript, Node.js, and TypeScript.

• Main rule set for Node.js files, though these rules are also used for TypeScript - where there is generally a high level of parity.
• Second rule set for compiled Node.js files (matching: "**/lib/src/*.js", "**/lib/src/**/*.js", "**/dist/src/*.js", "**/dist/src/**/*.js")
• Third rule set for other JavaScript files (matching: service.js, "**/js/*.js", "**/js/**/*.js")

TypeScript

TypeScript configuration establishes the directory structure and compile rules.

• Source code is taken from /src/ file
• Compiled code is written to /dist/src/

...because TypeScript does not clean up older compiled files, clean.ts is used (see below).

The current TypeScript configuration will produce:

• Compiled files (.js)
• Compiled map files (.js.map)
• Declaration files (.d.ts)
• Declaration map files (.d.ts.map)

Ignore Files

Git

Git ignore controls which files are sent to Bitbucket/GitHub,

Should include only the minimum number of files needed to reproduce development and testing.

Note: There is not a blanket ignore on /dist/src, the "git" script must be used.

NPM

NPM ignore controls which files are sent to NPM,

Should include only the minimum number of files needed to utilise the package.

Tests are ignored, as end-users don't need these - contributors can get them from Git.

package.json

Establishes "main" as "./dist/src/index" instead of "main.js".

Sets up three scripts:

• clean - compiles TypeScript, then see clean.ts
• build - runs "clean", then compiles TypeScript
• test - runs "build", then runs mocha tests
• git - runs "test", then runs "clean"

Before require/importing in another script, "build" must have been run.

Before committing to the Git repository, "git" must have been run.

Using npm init will update this with other NPM properties.

GitHub Actions

node.js.yml

If a commit/pull request is made onto the "master" branch, the "test" script is run.

npm-publish.yml

If a release is made through the GitHub repository, the package is published to both NPM and GitHub packages. Requires the NPM_TOKEN secret to be setup in the repository.

clean.ts

If you make an "example.ts" file and compile it, an "example.js" file is produced, if you later decide you don't need "example.ts" and delete it - the "example.js" file (and .js.map, .d.ts, .d.ts.map files) remains in the repository.

This usually isn't a massive deal, perhaps some wasted size on the NPM package until you notice and delete it, but if you're using functions that read directories (even if these functions aren't in your code - they are in Mocha) then these zombie files could cause problems.

clean.ts recursively selectively deletes everything inside of /dist/src/ that looks like a compiled JS file - either on request, or when tests are run - this ensures a clean working directory.