@zairakai/js-dev-tools

Why @zairakai/js-dev-tools?

Concept	Benefit
Unified Logic	The same quality gate for all your projects. Only the target (package or app) changes, not the rigor.
Concentrated Configs	Centralized, opinionated configurations for all your tools. Avoid configuration drift across projects.
Unified Workflow	One set of make commands to rule them all. Whether it's a small library or a large application, the quality gate remains the same.
Auto-Syncing CI	Automatically updates GitLab CI ref tags in your .gitlab-ci.yml when you update the package. Keep your pipelines current without manual effort.
Shared base	The ESLint, Prettier, Stylelint, Vitest, TypeScript and markdownlint rules live in @stanislas-poisson/js-dev-tools, which this package requires. The paths of this package (@zairakai/js-dev-tools/eslint, /prettier, ...) stay the same.
Zero Friction	Automated setup script handles the heavy lifting on install.

---

Features

Tool	Responsibility
ESLint	Flat config with TypeScript, Vue 3, and import rules.
Prettier	Opinionated formatter with SCSS and Tailwind support.
Stylelint	SCSS linting with modern property ordering.
Markdownlint	Consistent Markdown across all documentation.
Vitest	Unit testing with v8 coverage.
Knip	Dead code and unused dependency detection.
TypeScript	Shared tsconfig.base.json for strict mode builds.
GitLab CI	Reusable pipeline templates for npm packages and Laravel full-stack.
Git Hooks	Automated quality checks and ticket prefixing.
Makefile	Unified make quality, make test, make ci targets (delegated to core).
Shell Scripts	Automated setup and config publishing.

On install, the postinstall script:

• creates Makefile if missing (delegating to node_modules/@zairakai/js-dev-tools/tools/make/core.mk)
• creates .editorconfig
• creates config/dev-tools/eslint.config.js baseline
• reports optional packages not yet installed

---

Documentation

The documentation site has this guide and the reference of the API generated from the source with TypeDoc, for every released version (selector at the top right, next is main). Build it with cd docs && npm ci && npm run dev. It is published with GitLab Pages from main.

---

Install

npm install --save-dev @zairakai/js-dev-tools

For Laravel full-stack projects, pair with zairakai/laravel-dev-tools:

composer require --dev zairakai/laravel-dev-tools
npm install --save-dev @zairakai/js-dev-tools
php artisan dev-tools:publish --fullstack

---

Usage

make quality       # eslint + prettier + stylelint + knip + markdownlint + shellcheck
make quality-fix   # auto-fix all fixable issues
make test          # vitest
make test-all      # vitest + bats
make test-coverage # vitest with coverage report
make typecheck     # tsc --noEmit
make build         # tsup or tsc
make ci            # full pipeline simulation
make doctor        # environment diagnostics

---

Configuration

Extend the shared configs in your project files:

// eslint.config.js
export { default } from '@zairakai/js-dev-tools/eslint'

// prettier.config.js
export { default } from '@zairakai/js-dev-tools/prettier'

// stylelint.config.js
export { default } from '@zairakai/js-dev-tools/stylelint'

// vitest.config.js
import baseConfig from '@zairakai/js-dev-tools/vitest'
import { defineConfig } from 'vitest/config'
export default defineConfig({ ...baseConfig, test: { ...baseConfig.test } })

// tsconfig.json
{ "extends": "@zairakai/js-dev-tools/tsconfig" }

---

Publishing configs

Publish individual config files to config/dev-tools/ (never overwritten unless --force):

# All at once
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish

# By group
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=quality
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=style
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=testing
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=hooks
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=gitlab-ci
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=typescript

# Single files
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=eslint
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=prettier
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=stylelint
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=vitest
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=tsconfig

---

GitLab CI pipeline templates

Include in your consumer project's .gitlab-ci.yml:

# npm package pipeline
include:
  - project: 'zairakai/npm-packages/js-dev-tools'
    ref: 1.0.0          # pin to a release tag for reproducible builds
    file: '.gitlab/ci/pipeline-js-package.yml'

variables:
  CACHE_KEY: "my-package-v1"
  NPM_PACKAGE_NAME: "@myorg/my-package"

Available templates:

• .gitlab/ci/pipeline-js-package.yml — security → install → validate → quality → test → build → publish → release
• .gitlab/ci/pipeline-js-app.yml — JS quality + test jobs for Laravel full-stack apps

---

Automatic updates

The pipeline template updates the dependencies of a project by itself, and this package starts the update of the projects that use it. The rules are in the handbook (policies/dependency-management.md and policies/versioning.md).

• A weekly schedule with the variable UPDATE_DEPENDENCIES=true, or a pipeline started by the cascade, runs deps:update: it takes the minor and patch updates after a cooling period, opens a merge request into develop and merges it when its pipeline succeeds. Major versions are never applied.
• deps:release brings develop into main after such an update, and deps:tag tags main when a published range (dependencies, peerDependencies) changed. A project that changed only its development dependencies is not tagged: its published archive is the same.
• After the publication of a tag, deps:cascade waits for the version to be on the registry, then starts the update of the projects that have a .dependency-update.json.

The same script serves the PHP projects (composer.json): a job in the PHP image runs composer update, then this script commits, signs and opens the merge request, and deps:tag looks at require only. The jobs that sign (deps:update, deps:tag) run on an exact version of the node image (NODE_UPDATE_IMAGE, published on Docker Hub), because they need gpg and the image of the runner is not updated by itself.

The exceptions of a project live in .dependency-update.json at its root (everything is optional):

{
  "reject": ["typescript", "vue-tsc"],
  "cooldown": "3d",
  "tag": { "when": "runtime", "level": "patch" },
  "cascade": { "groups": ["zairakai/npm-packages"] }
}

tag.when is runtime (default), always or never, and tag.level is patch (default) or minor. Only the projects that others depend on need a cascade. The group variable GITLAB_TOKEN is used to open the merge requests and to tag.

Development

make quality          # full quality check
make test-all         # vitest + bats
make bats             # shell script tests only
make doctor           # environment diagnostics

---

Getting Help

[![License][license-badge]][license] [![Security Policy][security-badge]][security] [![Issues][issues-badge]][issues]

Made with ❤️ by [Zairakai][ecosystem]

Statistics

![Statistics of js-dev-tools][stats-card]