Skip to content
📦 A CLI toolkit for common scripts in JS/TS Auth0 projects
TypeScript JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.babelrc.js
.gitignore
.huskyrc.js
.prettierrc.js
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.hbs
README.md
config.js
jest.config.js
package-lock.json
package.json
tsconfig.json
tslint.json

README.md

auth0-toolkit

CLI toolkit for common scripts for JS/TS Auth0 projects


Inspired by "Tools without config", "The Melting Pot of JavaScript", and kcd-scripts.

Usage

  1. Create a project:
    • npm init new-auth0-project
    • If it's a TypeScript project: add types into package.json. For example:
      • { "types": "lib/index" }
  2. Install auth-toolkit:
    • npm install --save-dev auth0-toolkit
  3. Run the initialization script:
    • npx auth0-toolkit init
  4. Use included scripts:
    • npm run build -- --watch
    • npm run build:doc
    • npm run validate
    • npm run format
    • npm run lint
    • ... etc.

Configuration

This toolkit exposes a bin called auth0-toolkit. All scripts are stored in lib/scripts and all configuration files are stored in lib/config.

The toolkit determines whether a project is a TypeScript project or JavaScript project depending on whether the types property exists in package.json.

All included tools can have their configuration overwritten by adding flags to the command or by including configuration files in the root of your project. For example: running auth0-toolkit format will run Prettier with the included configuration, but having a .prettierrc in your project will cause the toolkit to use that configuration instead.

Overriding Configuration

During the toolkit setup process, configuration files for the libraries used by the toolkit are created in the project root. Libraries natively supporting an "extend" feature will use those by default to allow for toolkit configuration to be used as a starting point.

All configuration can be overridden with configuration files, package.json properties, or arguments passed to the toolkit binary.

API

Modules

build

Build project using TypeScript or Babel based on project type.

TypeScript

  • Copies js and d.ts files from src to lib using rsync, because tsc does not allow --allowJs and --declaration parameters at the same time.
  • Cleans target directory before build.

Babel

  • If no --ignore parameter presents, ignores by default: __tests__, __mocks__, __test_supplements__, __test_helpers__, *.(test|spec).(js|ts|jsx|tsx)
doc

Generates documentation files.

  • Generates README.md from the README.hbs handlebars template file and from JSDoc comments in source files.
  • Generates a table of contents.
  • If no --configure parameter is present and no configuration file is available, uses the builtin configuration provided by this library.
  • If no --files parameter given, uses all files recursively in src directory.
  • If no --template parameter given, uses README.hbs` in project root.
format

Formats project files using prettier.

  • If no config is provided (--config, prettier.config.js, or prettierrc in package.json), the default Prettier configuration will be used.
  • If no --ignore-path flag is provided or no .prettierignore file is present, the ignore file provided by the library will be used.
init

Initializes the project

The init script generates necessary files and updates package.json. This script is executed automatically during preinstall and postinstall stages. It can also be manually executed.

The following entries added to package.json:

  • scripts.build
  • scripts.test
  • scripts.watch
  • scripts.lint
  • scripts.format
  • scripts.validate
  • scripts.prepublishOnly

The following files are created:

  • .prettierrc.js
  • .prettierignore
  • .huskyrc.js
  • .eslintrc.js
  • tslint.json
  • tsconfig.json
lint

Lint project using TSLint or ESLint based on project type.

TSLint

  • If project has no tslint.json or --config is given, uses builtin configuration provided by this library.
  • If no files and --project argument is given, uses default TypeScript project directory provided by tsconfig.json in the root of the project.

Babel

  • If project has no ESLint configuration (.eslintrc.js or eslintConfig in package.json) or no --config is given, uses builtin configuration provided by this library.
  • If no --ignore-path argument is provided, uses .gitignore.
  • Uses --cache by default. (can be disabled with --no-cache)
precommit

The script that is automatically executed before a commit using lintstaged

  • If no config is provided (--config, lint-staged.config.js, or lint-staged in package.json), uses builtin configuration.
  • Executes lint-staged.
    • doc (if there's a build:doc script in package.json)
    • format and add to git
    • lint
    • test (executes test related to changed files)
test

Test project using Jest

  • Sets BABEL_ENV and NODE_ENV to test.
  • If not in CI, precommit stage, or following arguments are not present --no-watch, --coverage, --updateSnapshot or --watchAll, watches changes.
  • If no config is provided (--config, jest.config.js etc.) uses builtin configuration provided by this library.
validate

Runs all relevant validation steps on the project

Executes all the validation tasks that are relevent to the project from this list:

  • lint
  • test
  • typescript

If the event that triggers the validation script running is the precommit script, lint and test will be skipped since they are already ran separately.

build

Build project using TypeScript or Babel based on project type.

TypeScript

  • Copies js and d.ts files from src to lib using rsync, because tsc does not allow --allowJs and --declaration parameters at the same time.
  • Cleans target directory before build.

Babel

  • If no --ignore parameter presents, ignores by default: __tests__, __mocks__, __test_supplements__, __test_helpers__, *.(test|spec).(js|ts|jsx|tsx)

Properties

Name Default Description
[--out-dir] lib

Output destination for built files. (Babel)

[--outDir] lib

Output destination for built files. (Typescript)

[--no-clean]

If present, does not clean target directory.

[OTHERS]

All CLI options used by related binary. (tsc or babel)

Example

$ npm run build -- --watch --preserveWatchOutput
$ npx auth0-toolkit build
$ npx auth0-toolkit build --watch --preserveWatchOutput

doc

Generates documentation files.

  • Generates README.md from the README.hbs handlebars template file and from JSDoc comments in source files.
  • Generates a table of contents.
  • If no --configure parameter is present and no configuration file is available, uses the builtin configuration provided by this library.
  • If no --files parameter given, uses all files recursively in src directory.
  • If no --template parameter given, uses README.hbs` in project root.

Properties

Name Description
[OTHERS]

All CLI options used by related binary. (jsdoc2md)

Example

$ npm run build:doc
$ npx auth0-toolkit doc

format

Formats project files using prettier.

  • If no config is provided (--config, prettier.config.js, or prettierrc in package.json), the default Prettier configuration will be used.
  • If no --ignore-path flag is provided or no .prettierignore file is present, the ignore file provided by the library will be used.

Properties

Name Description
[--no-write]

If provided, files will not be written to disk. (Defaults to writing to disk)

[OTHERS]

All CLI options used by the related binary. (prettier)

Example

$ npm run format
$ npx auth0-scripts format

init

Initializes the project

The init script generates necessary files and updates package.json. This script is executed automatically during preinstall and postinstall stages. It can also be manually executed.

The following entries added to package.json:

  • scripts.build
  • scripts.test
  • scripts.watch
  • scripts.lint
  • scripts.format
  • scripts.validate
  • scripts.prepublishOnly

The following files are created:

  • .prettierrc.js
  • .prettierignore
  • .huskyrc.js
  • .eslintrc.js
  • tslint.json
  • tsconfig.json

Properties

Name Description
[...files]

Files to lint

[--no-cache]

Disables ESLint --cache arg which is added by this script.

[OTHERS]

All CLI options used by the related binary. (eslint or tslint)

Example

$ npx auth0-toolkit init

lint

Lint project using TSLint or ESLint based on project type.

TSLint

  • If project has no tslint.json or --config is given, uses builtin configuration provided by this library.
  • If no files and --project argument is given, uses default TypeScript project directory provided by tsconfig.json in the root of the project.

Babel

  • If project has no ESLint configuration (.eslintrc.js or eslintConfig in package.json) or no --config is given, uses builtin configuration provided by this library.
  • If no --ignore-path argument is provided, uses .gitignore.
  • Uses --cache by default. (can be disabled with --no-cache)

Properties

Name Description
[...files]

A list of files to lint.

[--no-cache]

Disables ESLint's --cache arg.

[OTHERS]

All CLI options used by related binary. (TSLint or ESLint)

Example

$ npm run lint
$ npm run lint my-file.ts -- --config my-config.json
$ npx auth0-toolkit lint
$ npx auth0-toolkit lint --no-cache
$ npx auth0-toolkit lint my-file.ts

precommit

The script that is automatically executed before a commit using lintstaged

  • If no config is provided (--config, lint-staged.config.js, or lint-staged in package.json), uses builtin configuration.
  • Executes lint-staged.
    • doc (if there's a build:doc script in package.json)
    • format and add to git
    • lint
    • test (executes test related to changed files)

Properties

Name Description
[OTHERS]

All CLI options used by the related binary. (lint-staged)

test

Test project using Jest

  • Sets BABEL_ENV and NODE_ENV to test.
  • If not in CI, precommit stage, or following arguments are not present --no-watch, --coverage, --updateSnapshot or --watchAll, watches changes.
  • If no config is provided (--config, jest.config.js etc.) uses builtin configuration provided by this library.

Properties

Name Description
[--no-watch]

If provided, tests run once. (Default is watch mode)

[OTHERS]

All CLI options used by the related binary. (jest)

Example

$ npm run test
$ npx auth0-toolkit test

validate

Runs all relevant validation steps on the project

Executes all the validation tasks that are relevent to the project from this list:

  • lint
  • test
  • typescript

If the event that triggers the validation script running is the precommit script, lint and test will be skipped since they are already ran separately.

Properties

Name Description
[...scripts]

A list of scripts to specifically run.

Example

$ npm run validate custom-validator
$ npx auth0-toolkit validate
$ npx auth0-toolkit validate custom-validator,another-validator

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

You can’t perform that action at this time.