A powerful TypeScript-based tool that ensures your JavaScript code is compatible with target environments using ESLint.
- π ES Version Validation: Verify your JavaScript code compatibility with specific ES versions (ES2015, ES2016, ES2017, and beyond)
- π Browser Support Verification: Validate browser compatibility using eslint-plugin-compat
- π― Smart Browser Detection: Automatically determine browser targets from ES version (optional)
- π Comprehensive Directory Scanning: Effortlessly scan directories for JavaScript files
- π GitHub Actions Integration: Seamlessly integrate with GitHub Actions workflows
- π¦ Flexible Installation: Install globally or use as a project dependency
npm install -g es-guard
npm install --save-dev es-guard
git clone https://github.com/mkayander/es-guard.git
cd es-guard
npm install
npm run build# Basic usage with auto-detected browsers es-guard # Validate specific directory es-guard build # Specify target ES version (year format) es-guard -t 2020 build # Specify target ES version (numeric format) es-guard -t 11 build # Use latest ES version es-guard -t latest build # Specify custom browser targets es-guard --browsers "> 0.5%, last 2 versions, Firefox ESR, not dead" dist # Display help information es-guard --help # Show version information es-guard --version
ES-Guard provides a comprehensive programmatic API for integration into your build tools, CI/CD pipelines, or custom scripts.
import { checkCompatibility } from "es-guard"; // Basic compatibility check const result = await checkCompatibility({ dir: "dist", target: "2020", }); console.log(`Found ${result.errors.length} errors and ${result.warnings.length} warnings`);
import { checkCompatibility, detectProjectConfig } from "es-guard"; // Auto-detect project configuration const config = detectProjectConfig(process.cwd()); if (config.target && config.outputDir) { const result = await checkCompatibility({ dir: config.outputDir, target: config.target, browsers: config.browserslist?.join(", "), }); }
import { checkCompatibility, detectProjectConfig } from "es-guard"; // Running in CI where working directory might be different const projectRoot = process.env.PROJECT_ROOT || process.cwd(); const buildDir = process.env.BUILD_DIR || "dist"; // Detect configuration from project root const config = detectProjectConfig(projectRoot); if (config.target) { const scanDir = config.outputDir || buildDir; const fullScanPath = path.isAbsolute(scanDir) ? scanDir : path.join(projectRoot, scanDir); const result = await checkCompatibility({ dir: fullScanPath, target: config.target, browsers: config.browserslist?.join(", "), }); // In CI, exit with error code if issues found if (result.errors.length > 0) { process.exit(1); } }
import { checkCompatibility, getBrowserTargetsFromString, setVerboseMode, validateConfig } from "es-guard"; // Validate configuration validateConfig({ dir: "dist", target: "2020", }); // Get browser targets for specific ES version const browsers = getBrowserTargetsFromString("2015"); // Enable verbose mode for detailed output setVerboseMode(true); // Run compatibility check const result = await checkCompatibility({ dir: "dist", target: "2020", browsers: "> 1%, last 2 versions, not dead, ie 11", }); // Process results result.errors.forEach((violation) => { console.log(`Error in ${violation.file}:`); violation.messages.forEach((message) => { console.log(` Line ${message.line}: ${message.message}`); }); });
ES-Guard includes full TypeScript support with proper type definitions:
import type { CompatibilityResult, Config, Violation } from "es-guard"; const config: Config = { dir: "dist", target: "2020", browsers: "> 1%, last 2 versions, not dead", }; const result: CompatibilityResult = await checkCompatibility(config);
See the examples directory for more comprehensive usage examples.
name: Validate Compatibility on: [push, pull_request] jobs: compatibility: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: "18" - run: npm install - run: npm run build - run: npx es-guard -t 2015 dist
| Parameter | Description | Default | Required |
|---|---|---|---|
path |
Directory to scan for JavaScript files | dist |
No |
target |
Target ES version | 2015 |
Yes |
browsers |
Browser targets for compatibility checking | Auto-detected from target | No |
| Option | Description | Default |
|---|---|---|
-t, --target <version> |
Target ES version | Auto-detected |
-b, --browsers <targets> |
Browser targets | Auto-detected |
| -v, --verbose | Enable verbose output | false |
| --skip | Continue on compatibility errors | false |
| --no-compat | Disable compat/compat rule - only report syntax errors | false |
The target parameter supports multiple formats:
- Year format:
2015,2016,2017, etc. - Numeric format:
6(ES2015),7(ES2016),11(ES2020), etc. - Latest:
latestfor the most recent ES version
The browsers parameter follows the Browserslist format. When not specified, browsers are automatically determined based on the ES target:
- ES2015/ES6:
> 1%, last 2 versions, not dead, ie 11 - ES2016-2017/ES7-8:
> 1%, last 2 versions, not dead, not ie 11 - ES2018-2019/ES9-10:
> 1%, last 2 versions, not dead, not ie 11, not op_mini all - ES2020+/ES11+:
> 1%, last 2 versions, not dead, not ie 11, not op_mini all, not android < 67
Custom browser target examples:
> 1%, last 2 versions, not dead, ie 11- Modern browsers with IE11 support> 0.5%, last 2 versions, Firefox ESR, not dead- Broader browser supportdefaults- Default Browserslist targetslast 1 version- Latest version of each browser
When running tests in CI environments, you may see error messages like:
Error: Directory "/path/to/nonexistent-directory" does not exist
Error: Invalid ES target: "invalid"
Warning: Could not lint directory
Error [BrowserslistError]: Unknown browser query
These are NOT test failures! These are expected outputs from tests that are designed to test error handling scenarios. The tests are actually passing successfully.
To properly handle test output in CI, configure your CI system to:
- Only fail on test exit codes (not on stderr output)
- Use the JUnit reporter for structured test results
- Check the JUnit XML file for actual test failures
# Run tests with JUnit output (recommended for CI) pnpm run test:junit # Run tests with coverage and JUnit output pnpm run test:junit:coverage # Check test results cat test-report.junit.xml
- name: Run Tests run: pnpm run test:junit:coverage - name: Upload Test Results uses: actions/upload-artifact@v3 with: name: test-results path: test-report.junit.xml retention-days: 30
npm install
npm run build
npm run dev
# Run all tests pnpm run test # Run tests in watch mode pnpm run test:dev # Run a specific test file pnpm run build && pnpm run test:only src/path/to/test.ts # Run a specific test by name pnpm run build && pnpm run test:only -t "test name" # Run tests without building first (requires previous build) pnpm run test:only -t "test name"
npm run lint
- Update the version in
package.json - Update the repository URL in
package.json - Build the project:
npm run build - Publish:
npm publish
MIT License - see LICENSE file for details.
- Fork the repository
- Create a feature branch
- Implement your changes
- Add tests where applicable
- Run the linter:
npm run lint - Submit a pull request
- π Issues
- π¬ Discussions