gh-secondsky-sap-skills-skills-sapui5-linter/references/configuration.md

UI5 Linter - Configuration Complete Reference

Source: https://github.com/UI5/linter/blob/main/README.md Last Updated: 2025-11-21 UI5 Linter Version: 1.20.5

---

Configuration Overview

UI5 Linter supports configuration files to customize linting behavior, define ignore patterns, and specify target files. Configuration is optional but recommended for projects with specific requirements.

---

Configuration File Location

Requirements

Configuration files must:

• Reside in the project root directory
• Be in the same directory as ui5.yaml and package.json
• Use one of the supported filenames

Supported Filenames

Filename	Module Type	Recommended
ui5lint.config.js	Auto-detected (based on package.json)	✅ General use
ui5lint.config.mjs	ES Module	✅ ESM projects
ui5lint.config.cjs	CommonJS	✅ CJS projects

Detection Order:

1. ui5lint.config.js
2. ui5lint.config.mjs
3. ui5lint.config.cjs

The first file found is used.

---

Configuration File Formats

ES Module (ESM) Format

File: ui5lint.config.mjs or ui5lint.config.js (with "type": "module" in package.json)

export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",
    "!webapp/test/integration/**",
  ],
  files: [
    "webapp/**/*.js",
    "webapp/**/*.xml",
  ],
};

When to Use:

• Modern JavaScript projects
• Projects using "type": "module" in package.json
• New projects (recommended)

---

CommonJS Format

File: ui5lint.config.cjs or ui5lint.config.js (without "type": "module")

module.exports = {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",
    "!webapp/test/integration/**",
  ],
  files: [
    "webapp/**/*.js",
    "webapp/**/*.xml",
  ],
};

When to Use:

• Traditional Node.js projects
• Projects without ESM support
• Legacy projects

---

Configuration Options

ignores

Type: string[]

Description: Array of glob patterns to exclude files from analysis.

Default: [] (no files ignored)

Pattern Characteristics:

• Relative to project root
• Supports glob syntax (*, **, ?, [], {})
• Supports negation with ! prefix
• Order matters: Later patterns override earlier ones

Basic Examples:

export default {
  ignores: [
    // Ignore entire directory
    "webapp/thirdparty/**",

    // Ignore all test files
    "**/*.test.js",
    "**/*.spec.js",

    // Ignore specific file
    "webapp/libs/legacy.js",
  ],
};

Advanced Patterns:

export default {
  ignores: [
    // Ignore all test directories
    "webapp/test/**",

    // BUT include integration tests (negation)
    "!webapp/test/integration/**",

    // Ignore generated files
    "dist/**",
    "build/**",

    // Ignore third-party libraries
    "webapp/thirdparty/**",
    "webapp/vendor/**",
    "node_modules/**", // Usually excluded by default

    // Ignore specific file types
    "**/*.min.js",
    "**/*.bundle.js",
  ],
};

Negation Example:

export default {
  ignores: [
    // Ignore all test files
    "webapp/test/**",

    // Except integration tests
    "!webapp/test/integration/**",

    // And except this specific file
    "!webapp/test/TestUtils.js",
  ],
};

Pattern Order Matters:

// ❌ WRONG: Negation comes first, then overridden
export default {
  ignores: [
    "!webapp/test/integration/**", // Won't work as expected
    "webapp/test/**",              // This overrides above
  ],
};

// ✅ CORRECT: Broader pattern first, then negation
export default {
  ignores: [
    "webapp/test/**",              // Ignore all tests
    "!webapp/test/integration/**", // Except integration tests
  ],
};

Common Use Cases:

// UI5 Application
export default {
  ignores: [
    "webapp/thirdparty/**",     // Third-party libs
    "webapp/localService/**",   // Mock data
    "webapp/test/**",           // Tests
    "!webapp/test/integration/**", // Keep integration tests
  ],
};

// UI5 Library
export default {
  ignores: [
    "test/**",                  // Test files
    "docs/**",                  // Documentation
    ".internal/**",             // Internal dev files
  ],
};

// Fiori Elements App
export default {
  ignores: [
    "webapp/ext/**",            // Extensions (might use legacy patterns)
    "webapp/localService/**",   // Mock server
    "webapp/test/**",           // Tests
  ],
};

---

files

Type: string[]

Description: Array of glob patterns specifying which files to lint.

Default: All files in project (except default exclusions)

Restrictions:

• ❌ Cannot include files typically excluded (e.g., node_modules/)
• ❌ Cannot include non-webapp directories in applications
• ✅ Must use POSIX separators (/) regardless of platform

Basic Examples:

export default {
  files: [
    // Lint all JavaScript in webapp
    "webapp/**/*.js",

    // Lint all XML views
    "webapp/**/*.xml",

    // Lint manifest
    "webapp/manifest.json",
  ],
};

Target Specific Areas:

export default {
  files: [
    // Controllers only
    "webapp/controller/**/*.js",

    // Views and fragments
    "webapp/view/**/*.xml",
    "webapp/fragment/**/*.xml",

    // Component and manifest
    "webapp/Component.js",
    "webapp/manifest.json",
  ],
};

Multi-Language Projects:

export default {
  files: [
    // JavaScript
    "webapp/**/*.js",

    // TypeScript
    "webapp/**/*.ts",

    // XML
    "webapp/**/*.xml",

    // YAML
    "ui5.yaml",
    "ui5-*.yaml",
  ],
};

Library Projects:

export default {
  files: [
    "src/**/*.js",          // Source files
    "src/**/*.xml",         // Control templates
    "src/**/*.json",        // Metadata
  ],
};

---

Complete Configuration Examples

Example 1: Basic UI5 Application

// ui5lint.config.mjs
export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",
  ],
};

Explanation:

• Ignores third-party libraries
• Ignores all test files
• Lints everything else in the project

---

Example 2: Advanced Application with Selective Testing

// ui5lint.config.mjs
export default {
  ignores: [
    // Third-party code
    "webapp/thirdparty/**",
    "webapp/vendor/**",

    // Mock data
    "webapp/localService/**",

    // All tests
    "webapp/test/**",

    // Except integration and unit tests
    "!webapp/test/integration/**",
    "!webapp/test/unit/**",

    // Ignore generated files
    "dist/**",
    "build/**",

    // Ignore minified files
    "**/*.min.js",
  ],
  files: [
    "webapp/**/*.js",
    "webapp/**/*.xml",
    "webapp/manifest.json",
  ],
};

---

Example 3: UI5 Library

// ui5lint.config.mjs
export default {
  ignores: [
    "test/**",
    "docs/**",
    ".internal/**",
    "playground/**",
  ],
  files: [
    "src/**/*.js",
    "src/**/*.xml",
    "src/**/*.json",
  ],
};

---

Example 4: TypeScript Project

// ui5lint.config.mjs
export default {
  ignores: [
    "webapp/thirdparty/**",
    "dist/**",
    "**/*.d.ts", // Ignore type definitions
  ],
  files: [
    "webapp/**/*.ts",
    "webapp/**/*.xml",
    "webapp/manifest.json",
  ],
};

---

Example 5: Monorepo with Multiple Apps

// ui5lint.config.mjs (in root)
export default {
  ignores: [
    "**/thirdparty/**",
    "**/test/**",
    "**/dist/**",
    "node_modules/**",
  ],
  files: [
    "apps/*/webapp/**/*.js",
    "apps/*/webapp/**/*.xml",
    "apps/*/webapp/manifest.json",
  ],
};

---

Example 6: Fiori Elements Application

// ui5lint.config.mjs
export default {
  ignores: [
    // Standard ignores
    "webapp/localService/**",
    "webapp/test/**",

    // Fiori Elements ignores
    "webapp/ext/**", // Extensions might use legacy patterns

    // Generated files
    "webapp/changes/**", // UI Adaptation changes
  ],
  files: [
    "webapp/manifest.json",
    "webapp/Component.js",
    "webapp/ext/**/*.js", // Lint extensions separately if needed
  ],
};

---

Using CLI Options to Override Config

CLI options can override or extend configuration file settings.

Override Ignore Patterns

# Add additional ignore pattern
ui5lint --ignore-pattern "webapp/experimental/**"

# Multiple additional patterns
ui5lint --ignore-pattern "**/*.old.js" --ignore-pattern "webapp/archive/**"

Note: CLI patterns are added to config file patterns, not replaced.

---

Override File Patterns

# Lint specific files (ignores config file 'files' option)
ui5lint "webapp/controller/**/*.js"

# Lint specific areas
ui5lint "webapp/view/" "webapp/fragment/"

Note: Positional file arguments override the config file files option.

---

Use Custom Config File

# Use different config
ui5lint --config config/lint-strict.config.js

# Use environment-specific config
ui5lint --config .ui5lint.ci.config.js

---

Integration with package.json

Add npm Script

{
  "scripts": {
    "lint": "ui5lint",
    "lint:fix": "ui5lint --fix",
    "lint:ci": "ui5lint --quiet --format json > lint-results.json"
  }
}

Usage

npm run lint
npm run lint:fix
npm run lint:ci

---

Integration with ui5.yaml

UI5 Linter reads ui5.yaml to understand project structure.

Custom ui5.yaml Location

ui5lint --ui5-config config/ui5-dev.yaml

Example ui5.yaml

specVersion: "3.0"
type: application
metadata:
  name: my.app

resources:
  configuration:
    paths:
      webapp: webapp

builder:
  resources:
    excludes:
      - "/test/**"
      - "/localService/**"

Note: UI5 Linter respects UI5 Tooling configuration but uses its own ignore patterns from config file.

---

Platform-Specific Considerations

Path Separators

Always use POSIX separators (/) in configuration files, regardless of platform:

// ✅ CORRECT (works on all platforms)
export default {
  ignores: [
    "webapp/thirdparty/**",
  ],
};

// ❌ WRONG (doesn't work)
export default {
  ignores: [
    "webapp\\thirdparty\\**", // Windows-style separators
  ],
};

Case Sensitivity

File systems:

• Linux/macOS: Case-sensitive
• Windows: Case-insensitive (usually)

Recommendation: Always match exact case in patterns.

// ✅ CORRECT: Match exact case
export default {
  ignores: [
    "webapp/ThirdParty/**", // If directory is "ThirdParty"
  ],
};

---

Debugging Configuration

Verbose Output

See which files are being processed:

ui5lint --verbose

Output:

verbose Loading configuration from /project/ui5lint.config.js
verbose Ignoring: webapp/thirdparty/**
verbose Processing: webapp/controller/Main.controller.js
verbose Processing: webapp/view/Main.view.xml
...

Test Patterns

Use --ignore-pattern to test without modifying config:

# Test if pattern works
ui5lint --ignore-pattern "webapp/test/**" --verbose

---

Common Configuration Patterns

Gradual Migration

// Start with strict ignores, gradually reduce
export default {
  ignores: [
    // Ignore everything except what we've migrated
    "webapp/**",

    // Include migrated files
    "!webapp/controller/Main.controller.js",
    "!webapp/view/Main.view.xml",
  ],
};

Focus on Specific Issues

// Lint manifest and component only
export default {
  files: [
    "webapp/manifest.json",
    "webapp/Component.js",
  ],
};

Exclude Generated Code

export default {
  ignores: [
    "**/*.gen.js",           // Generated JavaScript
    "**/gen/**",             // Generated directory
    "dist/**",               // Distribution build
    "build/**",              // Build output
    "webapp/changes/**",     // UI Adaptation changes
  ],
};

---

Environment-Specific Configurations

Development Config

// ui5lint.config.js
export default {
  ignores: [
    "webapp/thirdparty/**",
    // Allow test files in development
  ],
};

CI/CD Config

// .ui5lint.ci.config.js
export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",        // Ignore all tests in CI
    "webapp/localService/**",
  ],
};

Usage:

# CI pipeline
ui5lint --config .ui5lint.ci.config.js --quiet --format json

---

Best Practices

1. Start Broad, Then Narrow

// Start with broad ignores
export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",
  ],
};

// Later, as code improves, reduce ignores
export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/test/**",
    "!webapp/test/integration/**", // Now lint integration tests
  ],
};

2. Document Complex Patterns

export default {
  ignores: [
    // Third-party libraries (no control over code quality)
    "webapp/thirdparty/**",

    // Mock data (auto-generated from OData metadata)
    "webapp/localService/**",

    // Legacy code (planned for refactor in Q2)
    "webapp/legacy/**",
  ],
};

3. Use Consistent Patterns

// ✅ GOOD: Consistent pattern style
export default {
  ignores: [
    "webapp/thirdparty/**",
    "webapp/vendor/**",
    "webapp/test/**",
  ],
};

// ❌ BAD: Inconsistent patterns
export default {
  ignores: [
    "webapp/thirdparty/**",    // Double star
    "webapp/vendor/*",         // Single star
    "webapp/test",             // No star
  ],
};

4. Version Control Configuration

Commit configuration file:

git add ui5lint.config.js
git commit -m "Add UI5 Linter configuration"

Document in README:

## Linting

```bash
npm run lint

Configuration: ui5lint.config.js

---

## Troubleshooting

### Issue: Config File Not Found

**Symptoms**: Linter uses default settings despite config file existing.

**Solutions**:
1. Verify filename exactly matches: `ui5lint.config.{js,mjs,cjs}`
2. Ensure file is in project root (same as `ui5.yaml`)
3. Check file extension matches module type
4. Verify no syntax errors in config file

---

### Issue: Patterns Not Working

**Symptoms**: Files still linted despite ignore patterns.

**Solutions**:
1. Verify POSIX separators (`/` not `\`)
2. Check pattern order (broad first, negations last)
3. Use `--verbose` to see what's being processed
4. Test patterns with `--ignore-pattern` flag first

---

### Issue: Negation Patterns Not Working

**Symptoms**: Negated files still ignored.

**Solutions**:
1. Ensure negation comes **after** broader pattern:
   ```javascript
   ignores: [
     "webapp/test/**",              // First: broad
     "!webapp/test/integration/**", // Then: negation
   ]

2. Verify ! prefix is directly before pattern (no space)

---

Further Reading

• Main Repository: https://github.com/UI5/linter
• README: https://github.com/UI5/linter/blob/main/README.md
• CLI Options: See cli-options.md reference
• Node.js Glob Patterns: https://github.com/isaacs/node-glob#glob-primer

---

Document Version: 1.0 Last Verified: 2025-11-21 Next Review: 2026-02-21