README

Centralized collection of configuration and tooling used across all @brnshkr projects.

👋 About the Project
📚 Documentation
🧰 Prerequisites
🚀 Installation
👀 Usage
🧩 Custom Rules
❤️ Contributing
- 💄 Commit Style
- ⚙️ Workflows
🔖 Versioning
📃 License
🌐 Acknowledgments

👋 About the Project

@brnshkr/config is a centralized, opinionated collection of shared configuration files, tooling, and workflows for JavaScript and PHP projects. It helps standardizing linting, formatting, static analysis, and development workflows across repositories — reducing setup time, preventing config drift, and improving code quality and consistency.

❗ Note ❗
While you're more than welcome to use this in your own projects, the configurations are tailored specifically for the @brnshkr ecosystem and may not be a perfect fit elsewhere.

⬆

📚 Documentation

This README covers installation and usage. The full reference — custom rules, config builders, the Composer plugin, the shared Makefile, and the development setup — lives in ./docs, organized by stack and tool.

⬆

🧰 Prerequisites

JS

Node.js >= v24.15 or Bun >= v1.4 (Older versions may work, but are untested)
Any JavaScript package manager (Bun, Yarn, PNPM, NPM)

PHP

PHP >= 8.5 (Older versions may work, but are untested)
Composer >= 2.9 (Older versions may work, but are untested)
PHP Extensions:
- json
- mbstring

⬆

🚀 Installation

Bun

bun a -D -E @brnshkr/config

Any other JavaScript package manager works the same way, e.g. yarn add -D -E @brnshkr/config, pnpm add -D -E @brnshkr/config or npm i -D -E @brnshkr/config.

Take a look at the peerDependencies in the package.json file and install the ones you need for the modules you want to use.

Composer

composer r --dev brnshkr/config

Take a look at the suggested packages in the composer.json file and install the ones you need for the modules you want to use.
To have the packages installed for you, pick the modules interactively:

composer brnshkr:config:setup

⬆

👀 Usage

This package provides configurations, not a hard requirement on how you run tools.

🎨 Configuration

Each tool reads a config file like the ones below. Put it wherever the tool looks for one, or anywhere else and point the tool to it with its --config option; @brnshkr projects keep them in ./conf.

To use the defaults as they are, re-export them:

// ./conf/eslint.dist.mjs

export { default } from '@brnshkr/config/eslint';

// ./conf/phpstan.dist.php

return include __DIR__ . '/../vendor/brnshkr/config/conf/phpstan.dist.php';

To customize them, pass your options to getConfig(). Take a look at the function signatures for exact details.

// ./conf/eslint.dist.mjs

import { getConfig } from '@brnshkr/config/eslint';

export default getConfig(/* customize */);

// ./conf/phpstan.dist.php

use Brnshkr\Config\PhpStan;

return PhpStan::getConfig(/* customize */);

The other config builders work the same way, with their module listed in the table below. PHPStan reads a .neon file by default and a .php one with --configuration, and both can include ours:

// ./conf/phpstan.dist.php

return [
    'includes' => [
        __DIR__ . '/../vendor/brnshkr/config/conf/phpstan.dist.php',
    ],
];

Every tool and its options are described in the docs.

Run Tooling

A few possible ways are listed below:

Option 1 — Run Tools Directly (Most Flexible)

Example calls, adjust as needed (these are the commands the make targets run)

# ESLint
bun --bun x eslint --config ./conf/eslint.dist.mjs --cache --cache-location ./.cache/eslint.cache.json --max-warnings 0 --fix

# Stylelint
bun --bun x stylelint --config ./conf/stylelint.dist.mjs --config-basedir ./ --cache --cache-location ./.cache/stylelint.cache.json --allow-empty-input --max-warnings 0 --ignore-path ./.gitignore --ignore-path ./.stylelintignore --fix './**/*.{css,less,scss,ejs,html,svelte,svg,vue,astro,xml}'

# markdownlint
bun --bun x markdownlint-cli2 --config ./conf/markdownlint.dist.mjs --fix './**/*.{md,markdown}'

# commitlint
bun --bun x commitlint --config ./conf/commitlint.dist.mjs --edit

# TypeScript
bun --bun x tsc --project ./tsconfig.json --noEmit

# Vitest
bun --bun x vitest --config ./conf/vitest.dist.mjs --run --passWithNoTests

# PHP CS Fixer
./vendor/bin/php-cs-fixer fix --config ./conf/php-cs-fixer.dist.php --show-progress=dots -v

# Rector
./vendor/bin/rector process --config ./conf/rector.dist.php --memory-limit=-1

# PHPStan
./vendor/bin/phpstan analyze --configuration ./conf/phpstan.dist.php --memory-limit=-1 -vv

# Twig CS Fixer
./vendor/bin/twig-cs-fixer lint --fix --config ./conf/twig-cs-fixer.dist.php -v

# PHPUnit
./vendor/bin/phpunit --configuration ./conf/phpunit.dist.xml

# semgrep
semgrep scan --config p/default --config ./conf/semgrep.dist.yaml --error --quiet --metrics off --disable-version-check --no-rewrite-rule-ids

# hadolint
hadolint --config ./conf/hadolint.dist.yaml ./Dockerfile

# actionlint
actionlint -config-file ./conf/actionlint.dist.yaml

Option 2 — Run Make Targets (@brnshkr Convention)

Your own Makefile includes this one. Copy the starter rather than writing the include by hand: it guards the include, so a fresh clone can run a plain make before anything is installed.

cp -v ./node_modules/@brnshkr/config/conf/Makefile.dist ./Makefile \
  && make startup

When installed through Composer, the starter lives in ./vendor/brnshkr/config/conf/Makefile.dist instead.
A target appears once the tool it runs is installed, so make help lists what your repository actually has, make ci runs all of it, and make startup writes the .gitignore, .gitattributes and editor files you are still missing. The full reference is ./docs/Makefile.md.

These targets look for your configuration files in the ./conf directory (exactly how it is done in this project as well; see ./conf) and use the defaults of this package without one.

Tool	Module	Target	Optional configuration file
ESLint	`@brnshkr/config/eslint`	`make eslint`	`./conf/eslint.dist.mjs`
Stylelint	`@brnshkr/config/stylelint`	`make stylelint`	`./conf/stylelint.dist.mjs`
markdownlint	`@brnshkr/config/markdownlint`	`make markdownlint`	`./conf/markdownlint.dist.mjs`
commitlint	`@brnshkr/config/commitlint`	`make commitlint`	`./conf/commitlint.dist.mjs`
TypeScript	`@brnshkr/config/conf/tsconfig.json`	`make typescript`	`./tsconfig.json`
Vitest	`@brnshkr/config/vitest`	`make vitest`	`./conf/vitest.dist.mjs`
PHP CS Fixer	`Brnshkr\Config\PhpCsFixer`	`make php-cs-fixer`	`./conf/php-cs-fixer.dist.php`
Rector	`Brnshkr\Config\Rector`	`make rector`	`./conf/rector.dist.php`
PHPStan	`Brnshkr\Config\PhpStan`	`make phpstan`	`./conf/phpstan.dist.php`
Twig CS Fixer	`Brnshkr\Config\TwigCsFixer`	`make twig-cs-fixer`	`./conf/twig-cs-fixer.dist.php`
PHPUnit	—	`make phpunit`	`./conf/phpunit.dist.xml`
semgrep	—	`make semgrep`	`./conf/semgrep.dist.yaml`
hadolint	—	`make hadolint`	`./conf/hadolint.dist.yaml`
actionlint	—	`make actionlint`	`./conf/actionlint.dist.yaml`

When using the ./conf directory it might be necessary to instruct your IDE to read these files correctly.
If you need a VS Code setup and have the specific extensions installed, make configs writes the settings they need into ./.vscode/settings.json, pointing at the files the targets use.

Composer Plugin

The Composer package also adds a few helper commands, see the Composer plugin docs.

⬆

🧩 Custom Rules

Both stacks ship custom rules on top of the upstream ones. Each rule is documented with examples in the Custom ESLint Rules docs and the Custom PHPStan Rules docs.

⬆

❤️ Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the project
Create your feature branch => git checkout -b feature/my-new-feature
Commit your changes => git commit -m 'feat(my-new-feature): add some awesome new feature'
Push to the branch => git push origin feature/my-new-feature
Open a pull request

New to the codebase? The Development docs cover environment setup and the day-to-day commands for both stacks.

Any help is always greatly appreciated 🙂

💄 Commit Style

This project mostly follows the Conventional Commits specification.
There are only a few differences. The main one is that the scope is required:
So instead of this commit message signature: <type>[optional scope]: <description>
You should use this one: <type><scope>: <description>
Further details can be found in the commitlint configuration.

⚙️ Workflows

See ./.github/workflows for more information.

⬆

🔖 Versioning

This project follows Semantic Versioning 2.0.0.
The NPM and Composer packages are versioned in sync, so a version change does not necessarily indicate a change in a specific package.

❗ Note ❗
Since changes to rules and dependencies are not considered breaking, even a patch release may introduce new errors in code that hasn't changed and break your CI without notice. We therefore strongly recommend pinning to an exact version (-E for the JS package managers, composer r --dev brnshkr/config:X.Y.Z for Composer) so updates stay opt-in and can be applied on your own schedule.

Changes Considered as Breaking Changes

Version requirement changes of Node.js, Bun, PHP or Composer
Changes that might break existing userland configs

Changes Considered as Non-Breaking Changes

Changes regarding used rules and their options
Version updates, introduction or removal of dependencies
Updates of minimum required versions of optional dependencies

⬆

📃 License

Distributed under the MIT License. See LICENSE for more information.

⬆

🌐 Acknowledgments

⬆

brnshkr / config

Package info

Security

Statistics