README

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

☄️ Bug Reports / Feature Requests »

Table of Contents

• 👋 About the Project
• 📚 Documentation
• ☕ JS
  • 🧰 Prerequisites
  • 🚀 Installation
    • 🎨 Custom
  • 👀 Usage
  • 🧩 Custom ESLint Rules
• 🐘 PHP
  • 🧰 Prerequisites
  • 🚀 Installation
    • 🎨 Custom
  • 👀 Usage
  • 🧩 Custom PHPStan Rules
• 🔨 TODOs / Roadmap
• ❤️ 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.

   ⬆   

☕ JS

🧰 Prerequisites

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

   ⬆   

🚀 Installation

Bun

bun a -D -E @brnshkr/config

Yarn

yarn add -D -E @brnshkr/config

PNPM

pnpm add -D -E @brnshkr/config

NPM

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.
Copy the starter Makefile once, and let it write the rest:

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

make startup installs each stack, writes every config and .gitignore the project is missing, and never touches a file that is already there.

   ⬆   

🎨 Custom

Take a look at the function signatures for exact details.

ESLint

// ./conf/eslint.mjs

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

export default getConfig(/* customize */);

Stylelint

// ./conf/stylelint.mjs

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

export default getConfig(/* customize */);

markdownlint

// ./conf/markdownlint.mjs

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

export default getConfig(/* customize */);

commitlint

// ./conf/commitlint.mjs

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

export default getConfig(/* customize */);

Vitest

// ./conf/vitest.mjs

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

export default getConfig(/* customize */);

   ⬆   

👀 Usage

Run Tooling

This package provides configurations, not a hard requirement on how you run tools.
A few possible ways are listed below:

Option 1 — Run Tools Directly (Most Flexible)

ESLint

Example call, adjust as needed

bun eslint --config ./conf/eslint.mjs --cache --cache-location ./.cache/eslint.cache.json --max-warnings 0

Stylelint

Example call, adjust as needed

bun stylelint --config ./conf/stylelint.mjs --config-basedir ./ --cache --cache-location ./.cache/stylelint.cache.json --max-warnings 0 "**/*.{css,ejs,html,less,postcss,scss,svelte,svg,vue}"

markdownlint

Example call, adjust as needed

bun markdownlint-cli2 --config ./conf/markdownlint.mjs "**/*.md"

commitlint

Example call, adjust as needed

bun commitlint --config ./conf/commitlint.mjs --edit

Option 2 — Run Make Targets (@brnshkr Convention)

For these targets to work you need to follow the convention of putting your configuration files into the ./conf directory (Exactly how it is done in this project as well; see ./conf).

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 make bootstrap before anything is installed.

cp -v ./node_modules/@brnshkr/config/conf/Makefile.dist ./Makefile

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 any config you are still missing. The full reference is docs/Makefile.md.

ESLint (TypeScript Only)

Expected configuration file: ./conf/eslint.mjs

make eslint

Stylelint

Expected configuration file: ./conf/stylelint.mjs

make stylelint

markdownlint

Expected configuration file: ./conf/markdownlint.mjs

make markdownlint

commitlint

Expected configuration file: ./conf/commitlint.mjs

make commitlint

IDE Setup

When using the recommended way of putting config files into 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 you can take a look at the Project specific section in ./.vscode/settings.json.

   ⬆   

🧩 Custom ESLint Rules

The default ESLint configuration ships a small brnshkr plugin that contributes a handful of project-specific rules, all enabled out of the box. Each rule is documented with examples in the Custom ESLint Rules docs.

   ⬆   

🐘 PHP

🧰 Prerequisites

• 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

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.
Copy the starter Makefile once, and let it write the rest:

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

make startup installs each stack, writes every config and .gitignore the project is missing, and never touches a file that is already there.

To have the packages installed for you, pick the modules interactively:

composer brnshkr:config:setup

   ⬆   

🎨 Custom

Take a look at the function signatures for exact details.

PHP CS Fixer

<?php
// ./conf/php-cs-fixer.dist.php

declare(strict_types=1);

use Brnshkr\Config\PhpCsFixer;

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

Rector

<?php
// ./conf/rector.dist.php

declare(strict_types=1);

use Brnshkr\Config\Rector;

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

PHPStan

<?php
// ./conf/phpstan.dist.php

declare(strict_types=1);

use Brnshkr\Config\PhpStan;

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

Twig CS Fixer

<?php
// ./conf/twig-cs-fixer.dist.php

declare(strict_types=1);

use Brnshkr\Config\TwigCsFixer;

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

   ⬆   

👀 Usage

Run Tooling

This package provides configurations, not a hard requirement on how you run tools.
A few possible ways are listed below:

Option 1 — Run Tools Directly (Most Flexible)

PHP CS Fixer

Example call, adjust as needed

php ./vendor/bin/php-cs-fixer fix --config ./conf/php-cs-fixer.php -v --show-progress=dots

Rector

Example call, adjust as needed

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

PHPStan

Example call, adjust as needed

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

Twig CS Fixer

Example call, adjust as needed

php ./vendor/bin/twig-cs-fixer fix --config ./conf/twig-cs-fixer.php -v

Option 2 — Run Make Targets (@brnshkr Convention)

For these targets to work you need to follow the convention of putting your configuration files into the ./conf directory (Exactly how it is done in this project as well; see ./conf).

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

cp -v ./vendor/brnshkr/config/conf/Makefile.dist ./Makefile

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 any config you are still missing. The full reference is docs/Makefile.md.

PHP CS Fixer

Expected configuration file: ./conf/php-cs-fixer.php

make php-cs-fixer

Rector

Expected configuration file: ./conf/rector.php

make rector

PHPStan

Expected configuration file: ./conf/phpstan.php

make phpstan

Twig CS Fixer

Expected configuration file: ./conf/twig-cs-fixer.php

make twig-cs-fixer

IDE Setup

When using the recommended way of putting config files into 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 you can take a look at the Project specific section in ./.vscode/settings.json.

Plugin Commands

Overview of all commands provided by the composer plugin.
For full usage run composer help <command>, composer <command> --help or composer <command> -h.

   ⬆   

🧩 Custom PHPStan Rules

Beyond the upstream rule set, the default configuration ships a number of custom PHPStan rules in two flavors. Standalone rules are general-purpose checks enabled out of the box, while architecture presets are opinionated bundles of class-placement and isolation rules tailored to a specific framework or architecture style — opt-in and configured through setArchitecture(). Both are documented with examples in the Custom PHPStan Rules docs.

   ⬆   

🔨 TODOs / Roadmap

• Expand ⚙️ Workflows section in readme
• Add Vue support
• Add React support
• Add Tailwind support via https://github.com/schoero/eslint-plugin-better-tailwindcss
• Improve test setup

Any help is always greatly appreciated 🙂

   ⬆   

❤️ 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!

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

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

💄 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

• TypeScript
• ESLint
• markdownlint-cli2
• Stylelint
• commitlint
• @antfu/eslint-config
• PHP
• PHPStan
• Rector
• PHP-CS-Fixer
• Twig-CS-Fixer
• GNU Make
• Best-README-Template
• Choose an Open Source License
• Shields.io
• @brnshkr organization

   ⬆