auth0-toolkit
v0.0.1-alpha.61auth0-toolkit
CLI toolbox for common scripts for JS/TS Auth0 projects
Inspired by "Tools without config", "The Melting Pot of JavaScript", and kcd-scripts.
Usage
- Create a project:
npm init new-auth0-project
- If it's a TypeScript project: add
types
intopackage.json
. For example:{ "types": "lib/index" }
- Install auth-toolkit:
npm install --save-dev auth0-toolkit
- Run the initialization script:
npx auth0-toolkit init
- 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
, becausetsc
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)
- Copies js and d.ts files from src to lib using
- doc
Generates documentation files.
- Generates
README.md
from theREADME.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 insrc
directory. - If no
--template
parameter given, uses README.hbs` in project root.
- Generates
- format
Formats project files using
prettier
.- If no config is provided (
--config
,prettier.config.js
, orprettierrc
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.
- If no config is provided (
- init
Initializes the project
The
init
script generates necessary files and updatespackage.json
. This script is executed automatically duringpreinstall
andpostinstall
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 bytsconfig.json
in the root of the project.
Babel
- If project has no ESLint configuration (
.eslintrc.js
oreslintConfig
inpackage.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
)
- If project has no
- precommit
The script that is automatically executed before a commit using
lintstaged
- If no config is provided (
--config
,lint-staged.config.js
, orlint-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)
- If no config is provided (
- test
Test project using Jest
- Sets
BABEL_ENV
andNODE_ENV
totest
. - 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.
- Sets
- 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
andtest
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
, becausetsc
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. ( |
Example
$ npm run build -- --watch --preserveWatchOutput
$ npx auth0-toolkit build
$ npx auth0-toolkit build --watch --preserveWatchOutput
doc
Generates documentation files.
- Generates
README.md
from theREADME.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 insrc
directory. - If no
--template
parameter given, uses README.hbs` in project root.
Properties
Name | Description |
---|---|
[OTHERS] | All CLI options used by related binary. ( |
Example
$ npm run build:doc
$ npx auth0-toolkit doc
format
Formats project files using prettier
.
- If no config is provided (
--config
,prettier.config.js
, orprettierrc
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. ( |
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 |
[OTHERS] | All CLI options used by the related binary. ( |
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 bytsconfig.json
in the root of the project.
Babel
- If project has no ESLint configuration (
.eslintrc.js
oreslintConfig
inpackage.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 |
[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
, orlint-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. ( |
test
Test project using Jest
- Sets
BABEL_ENV
andNODE_ENV
totest
. - 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. ( |
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
License
This project is licensed under the MIT license. See the LICENSE file for more info.