@envsa/shared-config

🔬 @envsa/shared-config

A collection of shared configurations for various linters and formatting tools. All managed as a single dependency, and invoked via a single command.

Table of contents

• Overview
• Getting started
• Usage
• Implementation notes
• Development notes
• Credits
• License

Overview

This project attempts to consolidate most of the configuration and tooling shared by my open-source and internal TypeScript / Node based projects into a single dependency.

Tools

It takes care of dependencies and configurations for the following tools:

• CSpell
• ESLint (including Svelte, and TypeScript support)
• mdat
• Prettier (including a bunch of extra plugins)
• Stylelint
• VS Code (extension recommendations and extension settings)
• Minimal repo boilerplate (.npmrc, .gitignore, etc.)

Packages

This readme is for the @envsa/shared-config package, which depends on a number of tool-specific packages included in the kitschpatrol/shared-config monorepo on GitHub, each of which is documented in its respective readme, linked below:

• @envsa/cspell-config
• @envsa/eslint-config
• @envsa/mdat-config
• @envsa/prettier-config
• @envsa/repo-config
• @envsa/stylelint-config

Any of these may be installed and run on their own via CLI if desired. However, in general, the idea is to use @envsa/shared-config to easily run them all simultaneously over a repo with a single command with options to either check or (where possible) fix problems, with output aggregated into a single report.

Getting started

Dependencies

Node 18+ and pnpm are required. It probably works with NPM and yarn, but I haven't tested it.

Installation

Quick start from scratch:

Bootstrap a new project and open in VS Code:

git init && pnpm init && pnpm pkg set type="module" && pnpm dlx @envsa/repo-config --init && pnpm add -D @envsa/shared-config && pnpm shared-config --init && pnpm i && code .

Quick add to an existing project:

This might overwrite certain config files, so commit first:

pnpm dlx @envsa/repo-config --init && pnpm i && pnpm add -D @envsa/shared-config && pnpm shared-config --init

Step-by-step:

1. Install the requisite .npmrc:

   pnpm dlx @envsa/repo-config --init
   

2. Install the package:

   pnpm add -D @envsa/shared-config
   

3. Add default config files for all the tools to your project root:

   pnpm shared-config --init
   

4. Add helper scripts to your package.json:

   These work a bit like npm-run-all to invoke all of the bundled tools.

   "scripts": {
     "format": "shared-config --fix",
     "lint": "shared-config --lint",
   }
   

Usage

Various VS Code plugins should "just work".

To lint your entire project, after configuring the package.json as shown above:

pnpm run lint

To run all of the tools in a potentially destructive "fix" capacity:

pnpm run format

CLI

Command: shared-config

A collection of shared configurations for various linters and formatting tools. All managed as a single dependency, and invoked via a single command.

Usage:

shared-config [<file|glob> ...]

Option	Argument	Description
--init -i		Initialize by copying starter config files to your project root.
--check -c		Check for and report issues. Same as shared-config.
--print-config -p	<path>	Print the effective configuration at a certain path.
--fix -f		Fix all auto-fixable issues, and report the un-fixable.
--help -h		Print this help info.
--version -v		Print the package version.

Recall that the @envsa/shared-config package aggregates integration and invocation of the other tool-specific packages in this monorepo. Running a cli command on shared-config effectively runs the same command against all the tool-specific packages.

Implementation notes

Package architecture

Each package has a simple /src/cli.ts file which defines the behavior of its eponymous binary. The build step turns these into node "binary" scripts, providing default implementations where feasible.

The monorepo must be kept intact, as the sub-packages depend on scripts in the parent during build.

Hoisting caveats

Pnpm considers module hoisting harmful, and I tend to agree, but certain exceptions are carved out as necessary:

• CSpell, mdat, ESLint, and Prettier all need to be hoisted via public-hoist-pattern to be accessible in pnpm exec scripts and to VS Code plugins.

• Even basic file-only packages like repo-config seem to need to be hoisted via for their bin scripts to be accessible via pnpm exec

• prettier and eslint packages are hoisted by default in pnpm

Development notes

The repo uses placeholders for the bin script for each tool to avoid circular dependency issues during pnpm install.

To tell git to ignore changes to the placeholders, run pnpm run bin-ignore.

For local development via pnpm, use file: dependency protocol instead of link:

Something to investigate: An approach to ignoring style rules in VS Code, and possibly migrate all style to

Credits

Eric Mika is the author of the original @kitschpatrol/shared-config project on which this is based.

License

MIT © Liam Rella