Design System ESLint Package

[alizedebray]

Context

The configuration of ESLint has changed significantly in recent versions. It has shifted from the Classic Configuration to the Flat Configuration, which has impacted how ESLint plugins are developed.

Glossary

To help make the discussion easier to follow, let's define a few key ESLint terms:

• Parser: A parser converts a file into a tree structure (called an AST). ESLint rules then work by traversing this tree.
• Plugin: A plugin is a set of ESLint rules.
• Configs: A config defines how a plugin is applied to project files and possibly which parser is used.

Classic vs. Flat Config: Quick Overview

Classic Config

In the classic config, each ESLint plugin (or parser) was referenced by the name of the package that contained it. This meant that for each plugin or parser you wanted to offer, you had to create a separate package.

Flat Config

The flat config is more flexible. It’s a JavaScript file where you can import the plugins, configs, and parsers you need as objects (instead of as strings). This means that newer ESLint packages can export multiple plugins, configs, and parsers within a single package.

Discussion Points

Plugin Grouping

In our Design System, ESLint can serve two purposes:

1. Helping with project migration from one version to another using fixable rules.
2. Enforcing consistent code commenting practices across all projects.

Questions:

• Should we address both of these use cases?
• Should these two use cases be bundled together in a single package?
• For the migration use case, will the rules be used just once or should they be applied permanently to projects?

Naming Convention

We need to establish a clear naming convention for all parts of the ESLint package:

• The main package (e.g., @swisspost/design-system-eslint)
• The plugins (e.g., post/eslint-plugin, post/eslint-plugin-migration)
• The configs (e.g., post/migration, post/migration/template)

---

Ressources:

• typescript-eslint repository
• angular-eslint repository

[alizedebray]

Resolution:
FigJam: https://www.figma.com/board/scV96bnubHbt2R33gBBDcF/Untitled?node-id=0-1&p=f&t=8rm6hepmXuToT5lc-0

We will creat two ESLint packages that will be part of the SwissPost Design System:

• @swisspost/design-system-eslint-local (Private Package):
  • This package is private and will be used internally in the swisspost/design-system repository.
  • It will export a configuration that can be used by all other projects inside the SwissPost Design System repository.
• @swisspost/design-system-eslint (Public Package):
  • This package is public and will be available for external use.
  • It contains two plugins that provide specific functionality:
    • swisspost-eslint/design-system: A set of custom rules that help lint projects that use the Design System libraries.
    • swisspost-eslint/design-system/migration: A set of rules for migrating a project from one version of the Design System to another. This plugin can be run using an npx command without needing to import it into your project.

All names are subject to change.

[oliverschuerch]

• I'm fine with the name of the public package and what it exports.
• For the private package, I would propose a different name like @swisspost/eslint-configs or @swisspost/eslint-shared-configs.

[gfellerph]

I'd definitely prefix the internal package with design system as well: @swisspost/design-system-X should be the default for all packages that we have (regretting the decision on the internet header package). I think I'd prefer shared over local, therefore my proposals would be

@swisspost/design-system-eslint-shared
@swisspost/design-system-eslint-workspace (because it's used within our workspace)

[oliverschuerch]

I'd be ok with @swisspost/design-system-eslint-shared, but the second proposal feels like to angular related to me 😆

[alizedebray]

I am fine with @swisspost/design-system-eslint-shared as well :)

[gfellerph]

I'd be ok with @swisspost/design-system-eslint-shared, but the second proposal feels like to angular related to me 😆

It's also pnpm terminology, e.g. pnpm-workspace.yaml for monorepo configuration, as well as in workspace dependencies "@swisspost/design-system-styles": "workspace:8.6.2".

[gfellerph]

@alizedebray should we follow the naming conventions suggested (not enforced) by eslint (https://eslint.org/docs/latest/extend/plugins#meta-data-in-plugins) for our external packages?

That would be
@swisspost/eslint-plugin-design-system for the package and
@swisspost/eslint-plugin-design-system for the custom rules plugin and
@swisspost/eslint-plugin-design-system-migrations or @swisspost/eslint-plugin-design-system/migrations for the migrations plugin

[oliverschuerch]

Fine for me.

[alizedebray]

I am fine with naming the plugins @swisspost/eslint-plugin-design-system and @swisspost/eslint-plugin-design-system-migrations, however I would keep the package named @swisspost/design-system-eslint.

[alizedebray]

@gfellerph @oliverschuerch
Angular is also splitting the ts and template rules into two different plugins.
Also, when declared in a config an alias is actually given to the plugin, for example Angular ts plugin is named "@angular-eslint/eslint-plugin-template" but it alias is simple "@angular-eslint/template" in the configs, this alias is used to prefix the rules.

To sum up with what we just defined, for us this would mean:

Do we agree?

[alizedebray]

Advantage is to have a clear boundary between rules that applies to the templates and rules that applies to TS files:

[gfellerph]

If we separate by file type, that would mean that the one for templates (.html) will apply to projects using Angular, but also projects using no framework. Ts based rules could also apply in react projects (not all files in there are .tsx). Would it make more sense to have Angular/React/X specific plugins? Do we even want to have framework specific rules in there? If we start with just one plugin and all the rules in there, how easy is it to separate in the future when needed?

[oliverschuerch]

Great explanation and exactly what we should do imo.
Thanks @alizedebray!

[alizedebray]

@gfellerph I meant that the plugins are split by language rather than file type.
Our ESLint package would offer one plugin per language (HTML, TypeScript, SCSS, we can even think of TSX). The projects would then use the configuration they need based on their code.
An Angular app might use the HTML and TypeScript configurations, while a React app would use the TypeScript and TSX configurations.
Here is an example on how the configs are used: https://github.com/angular-eslint/angular-eslint/tree/main/packages/angular-eslint/src/configs#altering-the-recommended-set-to-suit-your-project

We could also add framework-specific plugins later, then we would need parsers able to handle framework-specific tokens. But I suggest we wait and see if we need them.

The rules are added to the plugins manually so we can easily change them and as the projects only use the exported configs they will not need to change anything on their side.

[gfellerph]

Ok, I'll stop nagging ^^