A curated set of configurations and useful CLI tools for web projects.

[!NOTE] This package is pure ESM. This means you need to ensure to use an ESM-Compatible Environment (Your runtime or bundler must support ESM) and enable Package Type module by adding the following to you package.json:

"type": "module"

• 📖 Why use this?
• 📦 What’s included?
• ⚙️ Installation
• Prettier
• ESlint
  • Override configuration
  • Typescript Type aware rules
• Oxfmt
• Oxlint
  • Typescript Type aware rules
  • Running Oxlint and ESLint together
• Typescript
  • ts-reset
  • Utilities
• 🔧 CLI Tools
• 📜 License

📖 Why use this?

Even experienced developers can waste valuable time configuring tools from scratch. Instead of manually setting up linters, formatters, and TypeScript settings, this package provides a ready-to-use configuration that is both easy to implement and extensible. It helps maintain clean, consistent code without the overhead of ongoing tools configuration maintenance allowing users to choose between traditional options (e.g., Prettier, ESlint) and more performant alternatives (e.g., Oxfmt, Oxlint).

[!IMPORTANT] Please keep in mind that this is still a personal config with a lot of opinions. Changes might not always work for everyone and every use case.

If you are using this config directly, I suggest you review the changes every time you update. Or if you want more control, always feel free to fork it. Thanks!

📦 What’s included?

This package provides ready-to-use configurations for:

• Shared configs for Code Style & Linting: Pre-configured yet extensible setups for Prettier and ESLint, offering high-performance alternatives via Oxfmt and Oxlint.
• TypeScript: Best-practice default config and utilities.
• CLI Tools: Useful command-line tools for streamlining workflows

[!Tip] You can use these configurations as-is or extend them to suit your project's specific needs.

⚙️ Installation

1. To get started, install the package as a development dependency:

npm install ---save-dev @yunarch/config-web

2. Then, install the necessary dependencies for the tools you want to use:

// To use Prettier
npm install --save-dev prettier

// To use eslint
npm install --save-dev eslint

// To use Oxfmt
npm install --save-dev oxfmt

// To use Oxlint
npm install --save-dev oxlint oxlint-tsgolint

Prettier

The easiest way to use the prettier configuration as-is is to set it directly in your package.json:

"prettier": "@yunarch/config-web/prettier"

Or you can create a configuration file to also allow further customization:

import defaultConfig from '@yunarch/config-web/prettier';

/** @type {import("prettier").Options} */
export default {
  ...defaultConfig,
  // Add your overrides here...
};

[!TIP] Add a .prettierignore file to ignore certain files and folder completly or use the CLI option --ignore-path to indicate a path to a file containing patterns that describe files to ignore.

By default, Prettier looks for ./.gitignore and ./.prettierignore.

ESlint

To use the ESlint linter, create a ESlint configuration file:

// eslint.config.js
import { config } from '@yunarch/config-web/eslint';

export default config();

And that's it! However, if needed, you can configure each integration individually:

import { config } from '@yunarch/config-web/eslint';

export default config({
  typescript: true,
  jsdoc: false,
  import: false,
  // Others
});

The config function also accepts multiple custom configuration overrides:

import { config } from '@yunarch/config-web/eslint';

export default config(
  {
    // Configures for provided config
  },
  // From the second arguments they are ESLint Flat Configs
  // you can have multiple configs
  {
    files: ['**/*.ts'],
    rules: {},
  },
  {
    rules: {},
  }
);

Thanks to antfu/eslint-config for the inspiration, reference, and developed tools.

Override configuration

Thanks to eslint-flat-config-utils we returns a flat config composer where you can chain methods and compose the configuration in different ways.

// eslint.config.js
import { config } from '@yunarch/config-web/eslint';

export default config()
  // overrides any named configs
  .override('yunarch/unicorn/rules', {
    rules: {
      'unicorn/no-array-for-each': 'off',
    },
  })
  // Override a whole configuration by a custom function to replace the config entirely.
  .override('yunarch/perfectionist/rules', (config) => {
    return {
      ...config,
      rules: {
        'perfectionist/sort-imports': 'off',
      },
    };
  })
  // Provide overrides to multiple configs as an object map.
  // Same as calling override multiple times.
  .overrides({
    'yunarch/unicorn/rules': {
      rules: {
        'unicorn/no-array-for-each': 'off',
      },
    },
  })
  .overrideRules({
    // Override rules in all configs.
  });

[!TIP] There are other methods such as remove, removeRules, append, insertBefore, etc. These methods help you configure the linter to suit your specific needs.

Typescript Type aware rules

By providing the tsconfigPath in the typescript configuration it will automatically enable type aware rules which may/will impact the linter's performance.

import { config } from '@yunarch/config-web/eslint';

export default config({
  typescript: {
    tsconfigPath: './tsconfig.json',
  },
});

[!NOTE] You can pass disableTypeAware: true to disable type-aware rules while keeping the TypeScript parser configuration which will allow you to manually enable the type-aware rules you want.

Oxfmt

To use Oxfmt, create a .oxfmtrc.json configuration file and extend the shared preset:

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "extends": ["@yunarch/config-web/oxfmt"],
}

[!NOTE] Oxfmt uses ignorePatterns in its configuration file instead of .prettierignore file but for compatibility, .prettierignore file is also supported.

See Oxfmt ignore files for details.

[!CAUTION] Currently, Oxfmt does not extends configuration: https://github.com/oxc-project/oxc/issues/16394

Oxlint

To use the oxlint linter, create a .oxlintrc.json configuration file:

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "extends": ["@yunarch/config-web/oxlint"],
  "categories": { "correctness": "error", "perf": "error" },
  "options": {
    "reportUnusedDisableDirectives": "warn",
  },
  "rules": {
    // Add your rules overrides here...
  },
  "overrides": [
    // Add your configuration overrides here..
  ],
}

[!TIP] For optimal results, we recommend setting the categories correctness and perf to error as shown above. However, feel free to enable any categories you prefer or need.

[!CAUTION] Currently, Oxlint does not resolve configuration file paths automatically. To extend a config, you must explicitly provide the full path, like so: "extends": ["./node_modules/@yunarch/config-web/dist/config.oxlint.json"]

Typescript Type aware rules

Oxlint Type-aware linting requires an additional dependency:

npm install --save-dev oxlint-tsgolint

To run Oxlint with type-aware linting, enable the typeAware and/or typeCheck options in your .oxlintrc.json configuration file:

"options": {
  "typeAware": true,
  "typeCheck": true,
},

[!WARNING] Type-aware linting is powered by typescript-go so TypeScript 7.0+ is required.

Running Oxlint and ESLint together

If not all required rules are available in Oxlint, you can run Oxlint and ESLint side by side.

Because Oxlint is significantly faster than ESLint, it is recommended to run Oxlint first to catch errors early, then fall back to ESLint only when necessary:

oxlint && eslint

To offload rules to Oxlint and significantly reduce overall linting time, you can configure ESlint as follows:

import { config } from '@yunarch/config-web/eslint';

export default config({
  oxlint: {
    oxlintConfigPath: './.oxlintrc.json',
  },
});

This reduces duplicate diagnostics, can help cut down your linting time considerably, and allows ESLint to focus only on rules that Oxlint does not yet support.

[!NOTE] Once remaining important rules have been added in Oxlint you should consider moving fully to Oxlint if you want to use that one to simplify your setup and reduce the number of dependencies for your project.

Typescript

Create the tsconfig.json file with the following content:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@yunarch/config-web/tsconfig-base",
  // Add your overrides here...
}

Learn more from Typescript docs here.

ts-reset

This package also includes a ts-reset configuration to enhance TypeScript's built-in types. To use it, create a reset.d.ts file in your project with the following content:

import '@yunarch/config-web/ts-reset.d.ts';

Then, include this file in your tsconfig.json, for example:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@yunarch/config-web/tsconfig-base",
  "include": ["./reset.d.ts" /* other files... */],
  // Add your overrides here...
}

[!TIP] You can use a glob pattern like "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"] to automatically include all relevant files, so you don't have to add them manually.

Utilities

As an enhancement to the ts-reset, this package provides type-level utilities to help you write stricter, more maintainable TypeScript code.

TypeScript uses structural typing, which means it doesn't always prevent objects from having excess properties. While ts-reset modifies built-in types globally, these utilities are opt-in, allowing you to apply stricter typing only where you need it.

[!NOTE] This package only provides types, as the package is intended to be used as a devDependency only. So you need to create runtime type-safe wrappers. Each utility type includes usage guidance in its definition comments.

For example, using the exposed utility types, you can define strictly typed versions of Object.entries and Object.fromEntries, ensuring safer and more predictable object manipulation:

import type {
  ObjectEntries,
  ObjectFromEntries,
} from '@yunarch/config-web/ts-utils.d.ts';

// Strictly typed version of `Object.entries`
const typedObjectEntries: ObjectEntries = Object.entries;
const x1 = typedObjectEntries({ a: 1, b: 2 } as const);

// Strictly typed version of `Object.fromEntries`
const typedObjectFromEntries: ObjectFromEntries = Object.fromEntries;
const x2 = typedObjectFromEntries([['a', 1]] as const);

🔧 CLI Tools

This package ships with useful command-line tools to streamline your workflow.

• openapi-gen: CLI tool designed to convert OpenAPI 3.0/3.1 schemas to TypeScript type-safe model interfaces and web service clients.
• openapi-msw-lint: CLI tool designed to lint and identifying missing MSW (Mock Service Worker) handlers based on the OpenAPI generated services from openapi-gen. It analyzes your codebase to find where service methods are used and suggests appropriate handlers with detailed reporting.

[!IMPORTANT] These tools are a personal configuration with a lot of opinions. They might not work for everyone or every use case. Additionally, tools can be added or removed without being considered a breaking change.

📜 License

MIT License © 2025-Present @yunarch