{"id":21569434,"url":"https://github.com/naturalcycles/dev-lib","last_synced_at":"2025-04-10T14:07:09.532Z","repository":{"id":33153542,"uuid":"152873434","full_name":"NaturalCycles/dev-lib","owner":"NaturalCycles","description":"Configuration files and scripts shared between all js modules","archived":false,"fork":false,"pushed_at":"2025-03-30T10:09:35.000Z","size":4237,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-30T11:20:03.432Z","etag":null,"topics":["gitignore","husky","lint-staged","prettier","tslint"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NaturalCycles.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-13T13:14:35.000Z","updated_at":"2025-03-30T10:08:54.000Z","dependencies_parsed_at":"2023-10-20T16:41:48.405Z","dependency_job_id":"f05ffde8-b439-4608-98d6-e300b169bc0c","html_url":"https://github.com/NaturalCycles/dev-lib","commit_stats":{"total_commits":813,"total_committers":8,"mean_commits":101.625,"dds":"0.33333333333333337","last_synced_commit":"fdc53243f1b663b4cc6afffa2fd7ae1c88d6e42a"},"previous_names":["naturalcycles/shared-module"],"tags_count":540,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaturalCycles%2Fdev-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaturalCycles%2Fdev-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaturalCycles%2Fdev-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaturalCycles%2Fdev-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NaturalCycles","download_url":"https://codeload.github.com/NaturalCycles/dev-lib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248231931,"owners_count":21069428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitignore","husky","lint-staged","prettier","tslint"],"created_at":"2024-11-24T11:09:29.803Z","updated_at":"2025-04-10T14:07:09.516Z","avatar_url":"https://github.com/NaturalCycles.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## @naturalcycles/dev-lib\n\n\u003e Set of opinionated configuration files and tools for common project needs, to be shared between\n\u003e all modules. Enforces conventions between projects.\n\n[![npm](https://img.shields.io/npm/v/@naturalcycles/dev-lib/latest.svg)](https://www.npmjs.com/package/@naturalcycles/dev-lib)\n[![install size](https://packagephobia.now.sh/badge?p=@naturalcycles/dev-lib)](https://packagephobia.now.sh/result?p=@naturalcycles/dev-lib)\n[![Maintainability](https://api.codeclimate.com/v1/badges/7df5e4dc0514ff142b7b/maintainability)](https://codeclimate.com/github/NaturalCycles/dev-lib/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/7df5e4dc0514ff142b7b/test_coverage)](https://codeclimate.com/github/NaturalCycles/dev-lib/test_coverage)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n[![Known Vulnerabilities](https://snyk.io/package/npm/snyk/badge.svg)](https://snyk.io/package/npm/@naturalcycles/dev-lib)\n[![Actions](https://github.com/NaturalCycles/dev-lib/workflows/default/badge.svg)](https://github.com/NaturalCycles/dev-lib/actions)\n\n## Tools that dev-lib enables\n\n- Prettier\n- ESLint\n- Biome\n- Stylelint\n- Jest / Vitest\n- ktlint\n- actionlint\n- lint-staged\n\n## How to use\n\nInstall it:\n\n    yarn add -D @naturalcycles/dev-lib\n\nThis unlocks all commands listed below, e.g:\n\n    yarn dev-lib test\n    yarn dev-lib lint\n\n`yarn dev-lib` runs \"interactive mode\" that lets you explore available commands.\n\nBy default, it uses default configs for Prettier, ESLint, Stylelint, that are included in this\npackage (for convenience). You can override them by putting your own `prettier.config.js`,\n`eslint.config.js`, `stylelint.config.js` in the root folder of your project.\n\nUPD: these tools/linters would use default configs if absent:\n\n- commitlint\n- lint-staged\n\nThese tools require a respective config to run, otherwise they're not run. List of configs:\n\n- `jest.config.js`\n- `prettier.config.js`\n- `eslint.config.js` (eslint FLAT config)\n- `stylelint.config.js`\n\n## Conventions\n\nPrimary language: TypeScript (`*.ts`).\n\nAll files are linted and _prettified_ upon commit (using `husky`, `lint-staged` and `prettier`).\n\n### Folder structure\n\n- `/dist` target dir to put compiled files into (`*.js` and additional files like `*.json`)\n- `/dist-cjs` target for CommonJS files\n- `/dist-esm` target for ES Modules\n- `/src` for all source files\n- `/scripts` for all non-production source files / scripts.\n- `/src/test` for generic test-related files and utilities, integration tests.\n- `/src/test/mock`\n- `/src/@types`\n- `/src/env`\n- `/cfg` conventional folder to store and publish shared configs. E.g. shared `tsconfig.json` or\n  such.\n- `/resources` files that will be published to npm, but that are not \"source code\". E.g. json files,\n  schemas, configs, etc.\n- `/coverage` for unit test coverage\n- `/tmp`\n  - `/jest/unit.xml`\n  - `/jest/integration.xml`\n  - `/coverage-integration`\n- `/docs` for Docs (convention followed by Github Pages, Conventional commits, Vitepress, etc)\n\n### Yarn commands\n\nThese commands are available to be called as `yarn dev-lib \u003ccommand\u003e`.\n\n#### Build commands\n\n- `build`: \"Production build\". Does `del ./dist \u0026\u0026 build-copy \u0026\u0026 tsc-prod`\n- `bt`: \"Build \u0026 Test\". Does `del ./dist \u0026\u0026 tsc \u0026\u0026 tsc-scripts \u0026\u0026 test`\n- `lbt`: \"Lint, Build \u0026 Test\". Does `lint \u0026\u0026 tsc \u0026\u0026 test`\n- `build-esm-cjs`: \"Production build\" for browser-lib, will produce CJS output in `./dist` and ESM\n  output in `./dist-esm`. Will use `./tsconfig.{cjs|esm}.prod.json` if exists, otherwise\n  `tsconfig.prod.json`, which allows to override e.g compilation target.\n\n#### Test commands\n\nThere are 3 categories of tests supported:\n\n- Unit tests (default) `*.test.ts`\n- Integration tests `*.integration.test.ts`\n- Manual tests `*.manual.test.ts`\n\nUnit tests are default. All tests are run on `yarn dev-lib test`.\n\nIntegration tests (optional) allow to have a setup file (`src/test/setupJest.integration.ts`) where\nyou can define separate environment settings. You can use it to run so-called \"integration tests\" -\ntests that interface with outside world (network, DB, APIs, etc). While unit tests are restricted to\nnot use network calls.\n\nManual tests (optional) are sub-category of integration tests that you never want to run\nautomatically in any environment. They're useful to run tests manually every now and then.\n\nAll test commands set `TZ=UTC`. You can override it by providing `TZ` env variable **before**\nrunning a test command. Adds `APP_ENV=test` env var (for all runs except integration). Automatically\nadds `--silent` (and `JEST_SILENT` env var) if all tests are run.\n\n- `test`: runs unit tests (all tests _except_ `*.integration.test.ts` and `*.manual.test.ts`).\n  Detects `CI` env variable, adds `--coverage` if in CI. Uses `default` reporter in `!CI`, otherwise\n  `jest-junit` reporter.\n- `test-integration`: runs `*.integration.test.ts` with `jest.integration-test.config.js` config.\n- `test-manual`: runs `*.manual.test.ts` with `jest.manual-test.config.js`.\n- `test-leaks`: runs Jest with `--logHeapUsage --detectOpenHandles --detectLeaks`.\n\nFor unit tests (`yarn test`) these `setupFilesAfterEnv` will be used (if found) in that order:\n\n- `\u003crootDir\u003e/src/test/setupJest.ts`\n- `\u003crootDir\u003e/src/test/setupJest.unit.ts`\n\nFor integration tests (`yarn test-integration`) these `setupFilesAfterEnv` will be used (if found)\nin that order:\n\n- `\u003crootDir\u003e/src/test/setupJest.ts`\n- `\u003crootDir\u003e/src/test/setupJest.integration.ts`\n\nFor manual tests:\n\n- `\u003crootDir\u003e/src/test/setupJest.ts`\n- `\u003crootDir\u003e/src/test/setupJest.manual.ts`\n\n`yarn dev-lib test` runs tests in alphabetic order by default (internally it points\n`--testSequencer` to a pre-defined sequencer file that sorts all filenames alphabetically). Set\n`JEST_NO_ALPHABETIC` env variable to disable it.\n\n##### Shard support\n\nJest 28 introduced [--shard](https://jestjs.io/docs/cli#--shard) feature.\n\nSet `JEST_SHARDS` environment variable (e.g `export JEST_SHARDS=3`), so that your `yarn test*`\ncommands will automatically split your tests by N number of shards and execute them **one after\nanother** (serially, **not** in parallel). Might be helpful to avoid Jest's notorious memory leaks.\n\nIf you need to execute shards **in parallel**, you can follow e.g\n[this instruction](https://medium.com/@mfreundlich1/speed-up-your-jest-tests-with-shards-776e9f02f637).\n\n#### Lint commands\n\n- `lint`: runs Biome, ESLint, Stylelint, Prettier, actionlint, ktlint in the right order.\n\n  - `--commitOnChanges` will commit lint-modified changes and push them\n  - `--failOnChanges` will exit with status 1 in the end (will fail the command)\n\n- `eslint`: runs `eslint` on needed paths\n- `biome`: runs `biome` on needed paths\n- `stylelint`: runs `stylelint` on needed paths\n- `prettier`: runs just Prettier on needed paths\n\nPass `--no-fix` (or `--fix=false`) to disable the default `--fix` flag on linters. Useful to debug a\nlinter, or when linter behaves badly and corrupts your files (just happened to me with\n`eslint-plugin-vue`).\n\nPass `--ext` (e.g `--ext ts,html`) to override the list of ESLint extensions (default is\n`ts,tsx,vue` right now).\n\nFor Stylelint to be run, you need to manually install it in the target project:\n\n`yarn add -D stylelint stylelint-config-standard-scss`\n\nFor Biome to run you need to install it like this:\n\n`yarn add -D @biomejs/biome`\n\nand add `biome.jsonc` config to the root.\n\n##### ktlint\n\n`ktlint` will be used by lint-staged for all `**/*.{kt,kts}` files.\n\n~~Please install it with `brew install ktlint`.~~\n\nInstall it **locally** in you project by adding\n[`@naturalcycles/ktlint`](https://github.com/NaturalCycles/ktlint) to your **dev**Dependencies.\n\n#### Other commands\n\n- `up`: shortcut for `yarn upgrade` \u0026\u0026 `yarn patch-package` (if `patch-package` exists in the\n  project).\n\n## Non-extendable config files\n\nThese files cannot be _extended_, so they are instead copied into the target project: first time\nwhen seeding the project, later manually by running `yarn update-from-dev-lib`.\n\nThese files are **overwritten** in target project every time the mentioned command is run. So, be\ncareful! Solution is to either extend them in other way (e.g put more `.gitignore` files in\nsubfolders), OR PR to this project, if the need is generic.\n\n- `.editorconfig`\n- `.gitignore`\n- `.codeclimate.yml` (with some work it can be made extendable later)\n\n## Extendable config files\n\nThese files are meant to be extended in target project, so act as _recommended defaults_.\n\n- `husky.config.js`\n- `lint-staged.config.js`\n- `prettier.config.js`\n- `eslint.config.js`\n- `biome.jsonc`\n- `jest.config.js`\n- `vitest.config.mjs`\n\n## eslint\n\nPresence of `jest` is detected by checking if `node_modules/jest` exists.\n\nIf exists - `eslint-plugin-jest` recommended config (plus opinionated `dev-lib`'s rules) are\nenabled. Otherwise disabled ( to not cause \"jest not found\" errors).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaturalcycles%2Fdev-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaturalcycles%2Fdev-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaturalcycles%2Fdev-lib/lists"}