Nit-Picking Manager

    @naturalcycles/dev-lib
    TypeScript icon, indicating that this package has built-in type declarations

    13.12.0 • Public • Published

    @naturalcycles/dev-lib

    Set of opinionated configuration files and tools for common project needs, to be shared between all modules. Enforces conventions between projects.

    npm install size Maintainability Test Coverage code style: prettier Known Vulnerabilities Actions

    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. shared tsconfig.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, Vuepress, 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: does tsc -p tsconfig.prod.ts

    • tsc-scripts: does tsc -p ./scripts/tsconfig.ts --noEmit (type-checking for ./scripts)

    • build: "Development build". Checks that "everything compiles". Does del ./dist && tsc && tsc-scripts

    • bt: "Build & Test". Does del ./dist && tsc && tsc-scripts && test

    • btl: "Build, Test & Lint". Does lint-all && tsc && test

    • build-copy: copies additional files into dist folder (e.g *.json)

    • build-prod: "Production build". Does del ./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, otherwise tsconfig.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). Detects CI env variable, adds --coverage if in CI. Uses default reporter in !CI, otherwise jest-junit reporter. Includes fix for "CircleCI out of memory issue"
    • test-integration: runs *.integration.test.ts with jest.integration-test.config.js config.
    • test-manual: runs *.manual.test.ts with jest.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, 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: runs eslint on needed paths

    • stylelint-all: runs stylelint on needed paths

    • prettier-all: runs just Prettier on needed paths

    • lint-circleci: fails if .circleci/config.yml is invalid (CircleCI CLI must be installed before)

    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).

    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

    • init-from-dev-lib: copy config files from dev-lib/cfg/init to the project
    • update-from-dev-lib: copy config files from dev-lib/cfg/overwrite to the project
    • generate-build-info: generate buildInfo.json
      • --dir <someDir> will save it to given dir
      • --shell will also generate buildInfo.sh

    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)

    Keywords

    none

    Install

    npm i @naturalcycles/dev-lib

    DownloadsWeekly Downloads

    365

    Version

    13.12.0

    License

    MIT

    Unpacked Size

    96.7 kB

    Total Files

    133

    Last publish

    Collaborators

    • kirillgroshkov
    • cervicalmucus
    • kribor