or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-eslint-config-taro

Taro specific linting rules for ESLint providing comprehensive configurations for cross-platform mini-program development

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/eslint-config-taro@4.1.x

To install, run

npx @tessl/cli install tessl/npm-eslint-config-taro@4.1.0

index.mddocs/

ESLint Config Taro

ESLint Config Taro provides comprehensive ESLint configurations specifically designed for Taro cross-platform applications. It includes four main categories of linting rules: custom Taro-specific rules, variable definition rules, import/export rules, and JSX syntax rules. The configuration supports both JavaScript and TypeScript codebases with dedicated parser configurations and framework-specific variants for React, Preact, and Vue 3.

Package Information

  • Package Name: eslint-config-taro
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install eslint @babel/eslint-parser eslint-config-taro eslint-plugin-taro eslint-plugin-react eslint-plugin-import --save-dev

Core Imports

The package provides several configuration options that can be imported through ESLint configuration files:

// .eslintrc.js - Default configuration
module.exports = {
  extends: ['taro']
}
// .eslintrc.js - React-specific configuration
module.exports = {
  extends: ['taro/react']
}
// .eslintrc.js - Preact configuration
module.exports = {
  extends: ['taro/preact']
}
// .eslintrc.js - Vue 3 configuration
module.exports = {
  extends: ['taro/vue3']
}

Basic Usage

// .eslintrc.js
module.exports = {
  extends: ['taro'],
  env: {
    node: true,
    browser: true
  },
  rules: {
    // Override specific rules if needed
    'no-console': 'warn'
  }
}

For TypeScript projects, the configuration automatically applies TypeScript-specific rules when .ts or .tsx files are encountered.

Architecture

ESLint Config Taro is built around four main rule categories:

  • Base Configuration: Core ESLint setup with Babel and TypeScript parser configurations
  • Rule Modules: Specialized rule sets for imports, JSX, and variable handling
  • Framework Variants: Specific configurations for React, Preact, and Vue 3
  • HTML Restrictions: Forbidden HTML elements list for mini-program compatibility

Capabilities

Default Configuration

Main ESLint configuration providing comprehensive linting for Taro projects with automatic TypeScript support.

// Default export from index.js
module.exports = {
  root: true;
  extends: [
    './rules/jsx',
    './rules/imports', 
    './rules/variables'
  ].map(require.resolve);
  parser: '@babel/eslint-parser';
  parserOptions: {
    ecmaVersion: 2018;
    ecmaFeatures: {
      jsx: true;
    };
  };
  overrides: [{
    files: ['**/*.ts?(x)'];
    parser: string; // '@typescript-eslint/parser'
    parserOptions: {
      ecmaVersion: 2018;
      sourceType: 'module';
      ecmaFeatures: {
        jsx: boolean;
      };
      warnOnUnsupportedTypeScriptVersion: boolean;
    };
    plugins: ['@typescript-eslint/eslint-plugin'];
    rules: {
      'default-case': 'off';
      'no-dupe-class-members': 'off';
      'no-undef': 'off';
      '@typescript-eslint/consistent-type-assertions': 'warn';
      'no-array-constructor': 'off';
      '@typescript-eslint/no-array-constructor': 'warn';
      'no-use-before-define': 'off';
      '@typescript-eslint/no-use-before-define': [
        'warn',
        {
          functions: false;
          classes: false;
          variables: false;
          typedefs: false;
        }
      ];
      'no-unused-expressions': 'off';
      '@typescript-eslint/no-unused-expressions': [
        'error',
        {
          allowShortCircuit: boolean;
          allowTernary: boolean;
          allowTaggedTemplates: boolean;
        }
      ];
      'no-unused-vars': 'off';
      '@typescript-eslint/no-unused-vars': [
        'warn',
        {
          args: 'none';
          ignoreRestSiblings: boolean;
          varsIgnorePattern: string; // '^Nerv|^React'
        }
      ];
      'no-useless-constructor': 'off';
      '@typescript-eslint/no-useless-constructor': 'warn';
      'no-shadow': 'off';
      '@typescript-eslint/no-shadow': 'error';
    };
  }];
}

React Configuration

React-specific configuration extending the main config with React pragma and version detection.

// Export from react.js
module.exports = {
  // Inherits all properties from index.js
  settings: {
    react: {
      pragma: string;
      version: string;
    };
  };
}

Preact Configuration

Preact-specific configuration that re-exports the React configuration for Preact compatibility.

// Export from preact.js - re-exports react.js configuration
module.exports = Object.assign({}, require('./react'));

Vue 3 Configuration

Vue 3 specific configuration with Vue essential rules and Babel parser setup. Does not inherit from the base configuration.

// Export from vue3.js
module.exports = {
  extends: ['plugin:vue/vue3-essential'];
  parserOptions: {
    parser: string; // '@babel/eslint-parser'
  };
}

HTML Tags Restrictions

List of HTML elements forbidden in Taro projects with custom error messages.

// Export from html-tags.js
module.exports = [
  {
    element: string;
    message: string;
  }
];

Usage Example:

const htmlTags = require('eslint-config-taro/html-tags');
// Returns: [{ element: 'select', message: '请使用 Picker 组件代替 <select>' }]

// Used internally in JSX rules configuration:
const forbidElements = htmlTags.map(tag => ({
  element: tag.element,
  message: tag.message
}));

Rule Categories

Import Rules

Comprehensive import/export linting rules using eslint-plugin-import with Taro-specific module resolution.

Key Features:

  • ES6 module support with Node.js resolution
  • Taro core modules pre-configured (@tarojs/taro, @tarojs/components)
  • Import order and style enforcement
  • Module dependency validation

Rule Highlights:

  • import/no-commonjs: Enforces ES6 modules over CommonJS ([2, { allowPrimitiveModules: true }])
  • import/no-duplicates: Prevents duplicate imports ('error')
  • import/newline-after-import: Requires newline after imports ('error')
  • import/no-absolute-path: Forbids absolute path imports ('error')
  • import/first: Imports must come first (['error', 'absolute-first'])
  • import/no-webpack-loader-syntax: Forbids Webpack loader syntax ('error')

Import Settings:

settings: {
  'import/resolver': {
    node: {
      extensions: ['.mjs', '.js', '.json'];
    };
  };
  'import/extensions': ['.js', '.mjs', '.jsx'];
  'import/core-modules': ['@tarojs/taro', '@tarojs/components'];
}

JSX Rules

JSX and React-specific linting rules with React Hooks support and forbidden HTML elements.

Key Features:

  • React and React Hooks plugin integration
  • JSX syntax validation
  • Component and state management rules
  • HTML element restrictions for mini-program compatibility

Rule Highlights:

  • react-hooks/rules-of-hooks: Enforces React Hooks rules ('error')
  • react-hooks/exhaustive-deps: Warns about missing hook dependencies ('warn')
  • react/jsx-uses-react: Marks React as used in JSX (['error'])
  • react/no-danger: Prevents dangerous JSX properties (['error'])
  • react/forbid-elements: Restricts HTML elements per Taro requirements (['error', { forbid: forbidElements }])
  • jsx-quotes: Enforces single quotes in JSX (['error', 'prefer-single'])
  • react/jsx-pascal-case: Enforces PascalCase for components (['error', { allowAllCaps: true, ignore: [] }])
  • react/jsx-curly-spacing: Enforces spacing in JSX curly braces (['error', { when: 'never', allowMultiline: true }])
  • react/jsx-indent-props: Enforces JSX prop indentation (['error', 2])

JSX Parser Options:

parserOptions: {
  ecmaFeatures: {
    jsx: true;
  };
}

JSX Plugins:

plugins: ['react', 'react-hooks']

Variable Rules

Variable definition and scoping rules with browser API restrictions for mini-program compatibility.

Key Features:

  • Variable scoping and shadowing prevention
  • Browser API restrictions (window, document, etc.)
  • Undefined variable detection
  • Variable usage validation

Rule Highlights:

  • no-restricted-globals: Restricts browser-specific globals (['error', 'isFinite', 'isNaN'].concat(restrictedGlobals))
  • no-shadow: Prevents variable shadowing ('error')
  • no-undef: Requires variable declarations ('error')
  • no-unused-vars: Identifies unused variables (['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }])
  • no-use-before-define: Prevents premature variable usage (['error', { functions: false, classes: false, variables: false }])

Restricted Globals List:

const restrictedGlobals = [
  'addEventListener', 'blur', 'close', 'closed', 'confirm', 'defaultStatus',
  'event', 'external', 'defaultstatus', 'find', 'focus', 'frameElement',
  'frames', 'history', 'innerHeight', 'innerWidth', 'length', 'location',
  'locationbar', 'menubar', 'moveBy', 'moveTo', 'name', 'onblur', 'onerror',
  'onfocus', 'onload', 'onresize', 'onunload', 'open', 'opener', 'opera',
  'outerHeight', 'outerWidth', 'pageXOffset', 'pageYOffset', 'parent', 'print',
  'removeEventListener', 'resizeBy', 'resizeTo', 'screen', 'screenLeft',
  'screenTop', 'screenX', 'screenY', 'scroll', 'scrollbars', 'scrollBy',
  'scrollTo', 'scrollX', 'scrollY', 'self', 'status', 'statusbar', 'stop',
  'toolbar', 'top'
];

TypeScript Support

The configuration automatically applies TypeScript-specific rules when processing .ts or .tsx files:

TypeScript Rules Applied:

  • @typescript-eslint/consistent-type-assertions: Enforces consistent type assertions
  • @typescript-eslint/no-unused-vars: TypeScript-aware unused variable detection
  • @typescript-eslint/no-use-before-define: Prevents premature variable usage
  • @typescript-eslint/no-shadow: TypeScript-aware shadow detection

ESLint Rules Disabled for TypeScript:

  • no-undef: Disabled (TypeScript compiler handles this)
  • no-unused-vars: Replaced with TypeScript equivalent
  • default-case: Disabled (TypeScript's noFallthroughCasesInSwitch is preferred)

Dependencies

Required Dependencies

{
  "@babel/eslint-parser": "^7.24.1",
  "@typescript-eslint/parser": "^6.2.0", 
  "@typescript-eslint/eslint-plugin": "^6.2.0",
  "eslint-plugin-import": "^2.29.1"
}

Peer Dependencies

{
  "eslint": "^8",
  "eslint-plugin-react": "^7.33.2",
  "eslint-plugin-react-hooks": "^4.4.0", 
  "eslint-plugin-vue": "^8.0.0"
}

Peer Dependencies Metadata

{
  "eslint-plugin-react": {
    "optional": true
  },
  "eslint-plugin-react-hooks": {
    "optional": true  
  },
  "eslint-plugin-vue": {
    "optional": true
  }
}

Note: React and Vue plugins are optional peer dependencies based on the framework being used.

Configuration Examples

JavaScript Project

// .eslintrc.js
module.exports = {
  extends: ['taro'],
  env: {
    browser: true,
    node: true
  }
}

TypeScript + React Project

// .eslintrc.js  
module.exports = {
  extends: ['taro/react'],
  env: {
    browser: true,
    node: true
  },
  parserOptions: {
    project: './tsconfig.json'
  }
}

Vue 3 Project

// .eslintrc.js
module.exports = {
  extends: ['taro/vue3'],
  env: {
    browser: true,
    node: true
  }
}

Custom Rule Overrides

// .eslintrc.js
module.exports = {
  extends: ['taro'],
  rules: {
    // Allow console for debugging
    'no-console': 'warn',
    
    // Customize import order
    'import/order': ['error', {
      'groups': ['builtin', 'external', 'internal'],
      'newlines-between': 'always'
    }],
    
    // Custom JSX rules
    'react/jsx-props-no-spreading': 'off',
    
    // Override TypeScript-specific rules
    '@typescript-eslint/no-unused-vars': ['error', {
      'argsIgnorePattern': '^_',
      'varsIgnorePattern': '^_'
    }]
  },
  
  // Add custom environments or globals
  env: {
    'taro/taro': true
  },
  
  // Override for specific file patterns
  overrides: [
    {
      files: ['*.config.js', 'config/**/*.js'],
      env: {
        node: true
      },
      rules: {
        'import/no-commonjs': 'off'
      }
    }
  ]
}

Multi-Framework Project

// .eslintrc.js - Mixed React/Vue project
module.exports = {
  overrides: [
    {
      files: ['src/react/**/*.{js,jsx,ts,tsx}'],
      extends: ['taro/react']
    },
    {
      files: ['src/vue/**/*.vue'],
      extends: ['taro/vue3'],
      parser: 'vue-eslint-parser'
    }
  ]
}