@hs-web-team/eslint-config-node 2.1.2 → 3.0.0-next.11

package/.github/workflows/main.yml

@@ -11,13 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [20, 22]
+        node: [22, 24]
 
-    name: Node ${{ matrix.node }} sample
+    name: Node ${{ matrix.node }} lint
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Run unit tests
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
       - run: npm install

package/.github/workflows/pr.yml

@@ -11,13 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [20, 22]
+        node: [22, 24]
 
     name: Node ${{ matrix.node }} sample
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Run unit tests
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
       - run: npm install

package/.github/workflows/release.yml

@@ -7,12 +7,24 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           registry-url: 'https://registry.npmjs.org'
       - run: npm install
-      - run: npm publish
+      - name: Publish to npm
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if [[ "$VERSION" =~ -next\. ]]; then
+            echo "Publishing prerelease version $VERSION with tag 'next'"
+            npm publish --tag next
+          elif [[ "$VERSION" =~ -(alpha|beta|rc)\. ]]; then
+            echo "Publishing prerelease version $VERSION with tag 'next'"
+            npm publish --tag next
+          else
+            echo "Publishing stable version $VERSION"
+            npm publish
+          fi
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is an ESLint configuration package (`@hs-web-team/eslint-config-node`) for HubSpot Marketing WebTeam Node.js projects. It provides shared ESLint rules and Prettier configuration for backend Node.js projects.
+
+## Key Commands
+
+### Linting
+```bash
+npm run lint
+```
+Runs ESLint on the codebase with auto-fix enabled. Uses the configuration defined in `index.js`.
+
+### Testing in Projects
+When testing changes to this package in downstream projects, you'll typically:
+1. Make changes to the ESLint config in `index.js`
+2. Run `npm link` in this repository
+3. Run `npm link @hs-web-team/eslint-config-node` in the consuming project
+4. Test the linting behavior in the consuming project
+
+## Architecture
+
+### Core Configuration File
+- **`index.js`**: The main ESLint configuration export using ESLint 9's flat config format
+  - Uses `@eslint/js`, `typescript-eslint`, and `globals` packages
+  - Exports an array of configuration objects (flat config format)
+  - Structure:
+    1. Global ignores object
+    2. `js.configs.recommended` for JavaScript baseline
+    3. JavaScript-specific config for `**/*.{js,mjs,cjs}` files
+    4. Spreads `tseslint.configs.recommended` for TypeScript baseline
+    5. TypeScript-specific config for `**/*.{ts,mts,cts,tsx}` files
+  - Includes Node.js, ES2022, and Jest globals
+  - Common ignores: `node_modules`, `.serverless`, `.webpack`, `dist`, `eslint.config.js`
+  - Key custom rules: `no-console` (allows info/warn/error), `max-len` (120 chars), camelcase disabled
+
+### Prettier Integration
+- **`bin/add-prettier-scripts.js`**: Executable script that consuming projects can run to set up Prettier
+  - Uses CommonJS (`require`) syntax (different from the main package which is ESM)
+  - Adds `prettier:check` and `prettier:write` scripts to package.json
+  - Creates `.prettierrc.js` file that imports from this package's `.prettierrc.json`
+  - Creates `.prettierignore` file with sensible defaults (npm-shrinkwrap.json, package-lock.json, .eslintrc, *.html)
+- **`.prettierrc.json`**: Shared Prettier configuration
+  - 120 char width, single quotes, 2-space tabs, trailing commas
+  - Arrow parens: avoid, LF line endings, single attribute per line
+  - Override for YAML files: uses double quotes instead of single
+
+### Package Details
+- **Type**: ESM module (`"type": "module"`)
+- **Node requirement**: >= 22
+- **Main export**: `index.js`
+- **Binary command**: `add-prettier` maps to `bin/add-prettier-scripts.js`
+
+### Migration Context
+This package is currently on v3, which uses ESLint 9's flat config format. The project has migrated from:
+- v1 → v2: See `docs/MIGRATION-V2.md`
+- v2 → v3: See `docs/MIGRATION-V3.md` (ESLint 9 flat config migration requiring Node.js 22+)
+
+## Important Notes
+
+- This package is for **backend Node.js projects only**, not browser environments
+- The configuration uses ESLint 9's flat config format (not the legacy `.eslintrc` format)
+- Downstream projects extend this config in their `eslint.config.js` by spreading the imported config using `...wtConfig`
+- Mixed module systems: `bin/add-prettier-scripts.js` uses CommonJS (`require`) while the main package is ESM
+- CI runs on Node 22 and 24 (see `.github/workflows/pr.yml`)
+- No automated tests currently (`npm test` will fail with "Error: no test specified")

package/README.md

@@ -19,23 +19,34 @@ This is a list of ESLint rules that are recommended for use with **Hubspot Marke
     npm i -D @hs-web-team/eslint-config-node@latest
     ```
 
-2. Add to `.eslintrc` in project root directory
+2. Add to `eslint.config.js` in project root directory
 
-    ```json
-    {
-      "extends": "@hs-web-team/eslint-config-node"
-    }
-    ```
+    ```typescript
+    import wtConfig from '@hs-web-team/eslint-config-node';
 
-3. Extend the eslint on a project basis by adding rules to `.eslintrc` e.g.
+    export default [
+      ...wtConfig,
+    ];
+    ```
 
-    ```json
-    {
-      "extends": "@hs-web-team/eslint-config-node",
-      "settings": {
-        "import/resolver": "webpack"
-      }
-    }
+3. Extend the eslint on a project basis by adding rules to `eslint.config.js` e.g.
+
+    ```typescript
+    import wtConfig from '@hs-web-team/eslint-config-node';
+
+    export default [
+      // Add project-specific ignores here
+      {
+        ignores: ['dist/**'],
+      },
+      // Add project-specific rules here
+      {
+        rules: {
+          'no-console': 'error',
+        },
+      },
+      ...wtConfig, // This will include the shared rules from @hs-web-team/eslint-config-node
+    ];
     ```
 
 ## Where to use it
@@ -67,3 +78,7 @@ This package includes a utility script to automatically add Prettier configurati
 ## Migration from v1 to v2
 
 See [MIGRATION-V2.md](./docs/MIGRATION-V2.md)
+
+## Migration from v2 to v3
+
+See [MIGRATION-V3.md](./docs/MIGRATION-V3.md)

package/docs/MIGRATION-V3.md

@@ -0,0 +1,290 @@
+# Migration from v2 to v3
+
+## Steps to migrate
+
+> **Note**
+>
+> This migration requires Node.js v22 or higher and a **manual migration** from `.eslintrc` to `eslint.config.mjs`.
+
+- [ ] Upgrade to Node.js v22 or higher
+- [ ] Update the package: `npm install -D @hs-web-team/eslint-config-node@latest`
+- [ ] **Remove** `@hs-web-team/eslint-config-ts` from dependencies (no longer needed - TypeScript support is now included)
+- [ ] Remove the `--ext .js,.ts` flag from the ESLint command in your project's package.json
+- [ ] Manually create `eslint.config.mjs` (see [Manual Migration Guide](#manual-migration-guide) below)
+- [ ] Delete `.eslintrc` file
+- [ ] Run `npm run lint` to check for any errors
+- [ ] Fix any linting errors
+- [ ] Commit the changes
+- [ ] Create a PR
+- [ ] Get it approved
+- [ ] Merge it into `main`
+- [ ] Test everything in QA
+- [ ] Celebrate! 🎉
+
+> **Important**
+>
+> The automated migration script (`npx @eslint/migrate-config .eslintrc`) **will not work** for most projects migrating from ESLint 8 to ESLint 9. You must manually create the new `eslint.config.js` file.
+>
+> This is because:
+> - ESLint 9 uses a completely different flat config format
+> - The `@hs-web-team/eslint-config-ts` package is no longer needed (TypeScript support is built-in)
+> - Many ESLint plugins have changed their configuration APIs
+
+## Manual Migration Guide
+
+### Before: Typical `.eslintrc` file
+
+```json
+{
+  "extends": [
+    "@hs-web-team/eslint-config-node",
+    "@hs-web-team/eslint-config-ts"
+  ],
+  "rules": {
+    "no-restricted-syntax": 0,
+    "no-console": 0,
+    "no-param-reassign": 0,
+    "no-await-in-loop": 0,
+    "max-classes-per-file": 0,
+    "import/no-extraneous-dependencies": 0,
+    "@typescript-eslint/no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": true }],
+    "@typescript-eslint/no-unnecessary-condition": "error"
+  },
+  "overrides": [
+    {
+      "files": ["*.test.ts", "*.spec.ts"],
+      "rules": {
+        "no-unused-expressions": "off"
+      }
+    }
+  ],
+  "env": {
+    "jest": true
+  },
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "globals": {
+    "window": true
+  }
+}
+```
+
+### After: New `eslint.config.mjs` file
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Spread the base config (includes both JS and TS configs)
+  ...wtConfig,
+
+  // Add custom rules for all files
+  {
+    rules: {
+      'no-restricted-syntax': 'off',
+      'no-console': 'off',
+      'no-param-reassign': 'off',
+      'no-await-in-loop': 'off',
+      'max-classes-per-file': 'off',
+      'import/no-extraneous-dependencies': 'off',
+    },
+  },
+
+  // TypeScript-specific rules (applied only to TS files)
+  {
+    files: ['**/*.{ts,mts,cts,tsx}'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { vars: 'all', args: 'after-used', ignoreRestSiblings: true }
+      ],
+      '@typescript-eslint/no-unnecessary-condition': 'error',
+    },
+  },
+
+  // Test file overrides
+  {
+    files: ['**/*.test.{ts,js}', '**/*.spec.{ts,js}'],
+    rules: {
+      'no-unused-expressions': 'off',
+    },
+  },
+
+  // Global variables (if needed)
+  {
+    languageOptions: {
+      globals: {
+        window: 'readonly',
+      },
+    },
+  },
+];
+```
+
+### Key Migration Changes
+
+1. **No separate TypeScript config needed**: TypeScript support is now included in `@hs-web-team/eslint-config-node`, so you can remove `@hs-web-team/eslint-config-ts` from your dependencies.
+
+2. **Environment variables**: The `env` property is replaced with `languageOptions.globals`. Jest globals are already included in the base config, so you don't need to specify them again.
+
+3. **Parser options**: Move `parserOptions` inside `languageOptions.parserOptions` and apply only to TypeScript files.
+
+4. **Overrides become separate objects**: Instead of `overrides` array, create separate configuration objects with `files` patterns.
+
+5. **Use `'off'` instead of `0`**: While numbers still work, the string values (`'off'`, `'warn'`, `'error'`) are more readable.
+
+6. **Import as ES module**: Use `import` instead of `require`.
+
+## Extending the Configuration
+
+Once you've completed the migration, you can easily extend the configuration for specific needs:
+
+### Adding Rules for Specific File Patterns
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+
+export default [
+  ...wtConfig,
+  {
+    files: ['src/**/*.js'],
+    rules: {
+      'no-restricted-imports': ['error', 'lodash'],
+    },
+  },
+];
+```
+
+### Adding Custom Plugins
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import securityPlugin from 'eslint-plugin-security';
+
+export default [
+  ...wtConfig,
+  {
+    plugins: {
+      security: securityPlugin,
+    },
+    rules: {
+      'security/detect-object-injection': 'warn',
+    },
+  },
+];
+```
+
+### Adding Custom Ignores
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+
+export default [
+  ...wtConfig,
+  {
+    ignores: [
+      '**/coverage/**',
+      '**/build/**',
+      '**/*.config.js',
+    ],
+  },
+];
+```
+
+### Complex Example with Multiple Customizations
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import importPlugin from 'eslint-plugin-import';
+
+export default [
+  ...wtConfig,
+
+  // Global overrides
+  {
+    rules: {
+      'no-console': 'off',
+      'max-len': ['error', { code: 100 }],
+    },
+  },
+
+  // Import plugin configuration
+  {
+    plugins: {
+      import: importPlugin,
+    },
+    rules: {
+      'import/order': ['error', { 'newlines-between': 'always' }],
+      'import/no-duplicates': 'error',
+    },
+  },
+
+  // TypeScript-specific configuration
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/strict-boolean-expressions': 'error',
+    },
+  },
+
+  // Test files
+  {
+    files: ['**/*.test.{js,ts}', '**/__tests__/**'],
+    rules: {
+      'max-len': 'off',
+      'no-magic-numbers': 'off',
+    },
+  },
+
+  // Additional ignores
+  {
+    ignores: ['**/generated/**', '**/migrations/**'],
+  },
+];
+```
+
+## Common Issues
+
+### Module Type Warning
+
+If you created `eslint.config.js` instead of `eslint.config.mjs`, you may see this warning when running ESLint:
+
+```bash
+(node:40504) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///path/to/your/project/eslint.config.js?mtime=1762786140088 is not specified and it doesn't parse as CommonJS.
+Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
+To eliminate this warning, add "type": "module" to /path/to/your/project/package.json.
+```
+
+**Why this happens:** This ESLint config package uses ES modules (`"type": "module"`), and your `eslint.config.js` imports it using ES module syntax. If your project's `package.json` doesn't specify the module type, Node.js has to parse the file twice, causing the warning.
+
+**Solution (choose one):**
+
+**Option 1 (Recommended for CommonJS projects):** Rename the config file to explicitly mark it as an ES module:
+
+```bash
+mv eslint.config.js eslint.config.mjs
+```
+
+This is the recommended approach because it doesn't require any changes to your existing codebase.
+
+**Option 2 (Only if already using ES modules):** Add to your project's `package.json`:
+
+```jsonc
+{
+  "type": "module"
+}
+```
+
+> **Warning:** Option 2 requires migrating your entire project from CommonJS to ES modules. All `.js` files must use ES module syntax (import/export) or be renamed to `.cjs`. Only use this option if your project is already using ES modules throughout.

package/index.js

@@ -1,45 +1,69 @@
-module.exports = {
-  env: {
-    commonjs: true,
-    es2021: true,
-    node: true,
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+// Base rules for all JavaScript files
+const baseRules = {
+  'no-console': [
+    'error',
+    {
+      allow: ['info', 'warn', 'error'],
+    },
+  ],
+  camelcase: 'off',
+  'comma-dangle': ['warn', 'always-multiline'],
+  'arrow-parens': 0,
+  'no-plusplus': 0,
+  'no-underscore-dangle': 0,
+  'no-confusing-arrow': 0,
+  'import/no-unresolved': 0,
+  'import/prefer-default-export': 0,
+  'no-trailing-spaces': ['error', { skipBlankLines: true }],
+  'no-unused-expressions': ['warn', { allowTernary: true }],
+  'max-len': [
+    2,
+    {
+      code: 120,
+      ignoreStrings: true,
+      ignoreTemplateLiterals: true,
+    },
+  ],
+  'operator-linebreak': 0,
+  'implicit-arrow-linebreaks': 0,
+  'implicit-arrow-linebreak': 0,
+  'object-curly-newline': 0,
+  'newline-per-chained-call': 0,
+  indent: 0,
+  'function-paren-newline': 0,
+};
+
+// Common ignore patterns
+const commonIgnores = [
+  '**/node_modules/**',
+  '**/.serverless/**',
+  '**/.webpack/**',
+  '**/dist/**',
+  'eslint.config.js',
+];
+
+export default [
+  // Global ignores
+  {
+    ignores: commonIgnores,
   },
-  ignorePatterns: ['/node_modules/', '/.serverless/', '/.eslintrc.js', '/.webpack/'],
-  extends: ['airbnb-base'],
-  parserOptions: {
-    ecmaVersion: 'latest',
+  // Base config for all JavaScript files
+  js.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {...globals.node, ...globals.es2022, ...globals.jest},
+    },
+    rules: baseRules,
   },
-  rules: {
-    'no-console': [
-      'error',
-      {
-        allow: ['info', 'warn', 'error'],
-      },
-    ],
-    camelcase: 0,
-    'comma-dangle': 1,
-    'arrow-parens': 0,
-    'no-plusplus': 0,
-    'no-underscore-dangle': 0,
-    'no-confusing-arrow': 0,
-    'import/no-unresolved': 0,
-    'import/prefer-default-export': 0,
-    'no-trailing-spaces': [2, { skipBlankLines: true }],
-    'no-unused-expressions': [1, { allowTernary: true }],
-    'max-len': [
-      2,
-      {
-        code: 120,
-        ignoreStrings: true,
-        ignoreTemplateLiterals: true,
-      },
-    ],
-    'operator-linebreak': 0,
-    'implicit-arrow-linebreaks': 0,
-    'implicit-arrow-linebreak': 0,
-    'object-curly-newline': 0,
-    'newline-per-chained-call': 0,
-    indent: 0,
-    'function-paren-newline': 0,
+  // TypeScript config that extends the base config
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,mts,cts,tsx}'],
+    rules: baseRules,
   },
-};
+];

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@hs-web-team/eslint-config-node",
-  "version": "2.1.2",
+  "version": "3.0.0-next.11",
   "description": "HubSpot Marketing WebTeam ESLint rules for Node.js",
   "main": "index.js",
+  "type": "module",
   "scripts": {
     "lint": "npx eslint -c ./index.js *.js --fix",
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -11,7 +12,7 @@
     "node": ">=22"
   },
   "bin": {
-    "add-prettier": "./bin/add-prettier-scripts.js"
+    "add-prettier": "bin/add-prettier-scripts.js"
   },
   "repository": {
     "type": "git",
@@ -27,9 +28,15 @@
   },
   "homepage": "https://github.com/HubSpotWebTeam/wt-eslint-node#readme",
   "dependencies": {
-    "eslint": "^8.57.1",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-plugin-import": "^2.32.0",
-    "prettier": "^3.6.2"
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.39.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.1",
+    "eslint-formatter-checkstyle": "^9.0.1",
+    "globals": "^16.5.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.6.2",
+    "typescript-eslint": "^8.46.3"
   }
 }