@naturalcycles/dev-lib v13.51.3
@naturalcycles/dev-lib
Set of opinionated configuration files and tools for common project needs, to be shared between all modules. Enforces conventions between projects.
How to use
Install it:
yarn add -D @naturalcycles/dev-lib
This unlocks all commands listed below, e.g:
yarn test
yarn lint-all
By default, it uses default configs for Prettier, ESLint, Stylelint, that are included in this
package (for convenience). You can override them by putting your own prettier.config.js
,
.eslintrc.js
, stylelint.config.json
in the root folder of your project.
Conventions
Primary language: TypeScript (*.ts
).
All files are linted and prettified upon commit (using husky
, lint-staged
and prettier
).
Folder structure
/dist
target dir to put compiled files into (*.js
and additional files like*.json
)/dist-cjs
target for CommonJS files/dist-esm
target for ES Modules/src
for all source files/scripts
for all non-production source files / scripts./src/test
for generic test-related files and utilities, integration tests./src/test/mock
/src/@types
/src/env
/cfg
conventional folder to store and publish shared configs. E.g. sharedtsconfig.json
or such./resources
files that will be published to npm, but that are not "source code". E.g. json files, schemas, configs, etc./coverage
for unit test coverage/tmp
/jest/unit.xml
/jest/integration.xml
/coverage-integration
/docs
for Docs (convention followed by Github Pages, Conventional commits, Vitepress, etc)
Yarn commands
These commands are available to be called as yarn <command>
, because they are exposed as
npm scripts
in node_modules/.bin/
.
Build commands
tsc-prod
: doestsc -p tsconfig.prod.ts
tsc-scripts
: doestsc -p ./scripts/tsconfig.ts --noEmit
(type-checking for./scripts
)build
: "Development build". Checks that "everything compiles". Doesdel ./dist && tsc && tsc-scripts
bt
: "Build & Test". Doesdel ./dist && tsc && tsc-scripts && test
btl
: "Build, Test & Lint". Doeslint-all && tsc && test
build-copy
: copies additional files intodist
folder (e.g*.json
)build-prod
: "Production build". Doesdel ./dist && build-copy && tsc-prod
build-prod-esm-cjs
: "Production build" for browser-lib, will produce CJS output in./dist
and ESM output in./dist-esm
. Will use./tsconfig.{cjs|esm}.prod.json
if exists, otherwisetsconfig.prod.json
, which allows to override e.g compilation target.
Test commands
There are 3 categories of tests supported:
- Unit tests (default)
*.test.ts
- Integration tests
*.integration.test.ts
- Manual tests
*.manual.test.ts
Unit tests are default. All tests are run on yarn test
.
Integration tests (optional) allow to have a setup file (src/test/setupJest.integration.ts
) where
you can define separate environment settings. You can use it to run so-called "integration tests" -
tests that interface with outside world (network, DB, APIs, etc). While unit tests are restricted to
not use network calls.
Manual tests (optional) are sub-category of integration tests that you never want to run automatically in any environment. They're useful to run tests manually every now and then.
All test commands set TZ=UTC
. You can override it by providing TZ
env variable before
running a test command. Adds APP_ENV=test
env var (for all runs except integration). Automatically
adds --silent
(and JEST_SILENT
env var) if all tests are run.
test
: runs unit tests (all tests except*.integration.test.ts
and*.manual.test.ts
). DetectsCI
env variable, adds--coverage
if in CI. Usesdefault
reporter in!CI
, otherwisejest-junit
reporter. Includes fix for "CircleCI out of memory issue"test-integration
: runs*.integration.test.ts
withjest.integration-test.config.js
config.test-manual
: runs*.manual.test.ts
withjest.manual-test.config.js
.test-leaks
: runs Jest with--logHeapUsage --detectOpenHandles --detectLeaks
.
For unit tests (yarn test
) these setupFilesAfterEnv
will be used (if found) in that order:
<rootDir>/src/test/setupJest.ts
<rootDir>/src/test/setupJest.unit.ts
For integration tests (yarn test-integration
) these setupFilesAfterEnv
will be used (if found)
in that order:
<rootDir>/src/test/setupJest.ts
<rootDir>/src/test/setupJest.integration.ts
For manual tests:
<rootDir>/src/test/setupJest.ts
<rootDir>/src/test/setupJest.manual.ts
yarn test
runs tests in alphabetic order by default (internally it points --testSequencer
to a
pre-defined sequencer file that sorts all filenames alphabetically). Set JEST_NO_ALPHABETIC
env
variable to disable it.
Shard support (experimental)
Jest 28 introduced --shard feature.
Set JEST_SHARDS
environment variable (e.g export JEST_SHARDS=3
), so that your yarn test*
commands will automatically split your tests by N number of shards and execute them one after
another (serially, not in parallel). Might be helpful to avoid Jest's notorious memory leaks.
If you need to execute shards in parallel, you can follow e.g this instruction.
Lint commands
lint-all
: runs ESLint, Stylelint, Prettier, actionlint, ktlint in the right order.--commitOnChanges
will commit lint-modified changes and push them--failOnChanges
will exit with status 1 in the end (will fail the command)
eslint-all
: runseslint
on needed pathsstylelint-all
: runsstylelint
on needed pathsprettier-all
: runs just Prettier on needed paths
Pass --no-fix
(or --fix=false
) to disable the default --fix
flag on linters. Useful to debug a
linter, or when linter behaves badly and corrupts your files (just happened to me with
eslint-plugin-vue
).
Pass --ext
(e.g --ext ts,html
) to override the list of ESLint extensions (default is
ts,tsx,vue
right now).
For Stylelint to be run, you need to manually install it in the target project:
yarn add -D stylelint stylelint-config-standard-scss
ktlint
ktlint
will be used by lint-staged for all **/*.{kt,kts}
files.
Please install it with brew install ktlint
.
Install it locally in you project by adding
@naturalcycles/ktlint
to your devDependencies.
Other commands
up
: shortcut foryarn upgrade
&&yarn patch-package
(ifpatch-package
exists in the project).init-from-dev-lib
: copy config files fromdev-lib/cfg/init
to the projectupdate-from-dev-lib
: copy config files fromdev-lib/cfg/overwrite
to the project
Non-extendable config files
These files cannot be extended, so they are instead copied into the target project: first time
when seeding the project, later manually by running yarn update-from-dev-lib
.
These files are overwritten in target project every time the mentioned command is run. So, be
careful! Solution is to either extend them in other way (e.g put more .gitignore
files in
subfolders), OR PR to this project, if the need is generic.
.editorconfig
.gitignore
.codeclimate.yml
(with some work it can be made extendable later)
Extendable config files
These files are meant to be extended in target project, so act as recommended defaults.
husky.config.js
lint-staged.config.js
prettier.config.js
eslint.config.json
jest.config.js
eslint
Presence of jest
is detected by checking if node_modules/jest
exists.
If exists - eslint-plugin-jest
recommended config (plus opinionated dev-lib
's rules) are
enabled. Otherwise disabled ( to not cause "jest not found" errors)
27 days ago
27 days ago
28 days ago
28 days ago
1 month ago
1 month ago
1 month ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
10 months ago
9 months ago
8 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
7 months ago
7 months ago
5 months ago
6 months ago
10 months ago
6 months ago
7 months ago
6 months ago
7 months ago
7 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
8 months ago
9 months ago
9 months ago
8 months ago
8 months ago
8 months ago
10 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
8 months ago
9 months ago
8 months ago
9 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago