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
• Configuration
  • Overriding Configuration
• API
  • Modules
  • build
  • doc
  • format
  • init
  • lint
  • precommit
  • test
  • validate
• Author
• License

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

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

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

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

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

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

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

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

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.