ts-browser-compat

Check TypeScript projects for browser compatibility, using MDN browser-compat-data - the same data that powers caniuse.com.

Important note: This uses heuristics to report usage of APIs that may not be supported. The heuristics are not accurate in all cases - manually check the results.

Simple Usage

npx @journeyapps/ts-browser-compat -b firefox:55 -b safari_ios:13

Sample output:

AbortController - firefox 57, safari_ios 12.2
  src/client.ts:196
AbortController.abort - firefox 57, safari_ios 12.2
  src/client.ts:210
AbortController.signal - firefox 57, safari_ios 12.2
  src/client.ts:202
Blob.arrayBuffer - firefox 69, safari_ios 14
  src/convert.ts:64
Blob.text - firefox 69, safari_ios 14
  src/convert.ts:87
  src/convert.ts:93

Limitations

This project works by cross-referencing type references from DOM and built-in libraries in TypeScript, to the MDN browser compatibility data.

No support for checking CSS.
No support for checking HTML.
No support for checking DOM events.
Does not check for supported JavaScript syntax. Use target in tsconfig.json for this.
Limited support for checking JavaScript source files: It only works as well as the TypeScript compiler can infer the types.
Unpredictable results when a browser lists partial support for an API.
Potential for inaccuracies with mapping the TypeScript definition to the compatibility data.
Does not automatically build or check referenced projects.
Does not check implementation of dependencies with type declarations.
Does not detect safe API usage using guard statements.

Usage in a project

For regular use, add as a dependency:

npm install --save-dev @journeyapps/ts-browser-compat

Then create a ts-browser-compat.json config file:

{
  // List of minimum browser versions
  "browsers": {
    "firefox": "55",
    "safari_ios": "13"
  },
  // Optional path to TypeScript projects - defaults to current dir
  "path": ["src", "web"],
  //
  "polyfills": [
    // Mark a specific property or method as implemented
    "Promise.finally",
    // This only matches the contructor, no properties or methods
    "AbortController",
    // This matches the constructor and all properties and methods
    "Blob.*"
  ],
  "ignore": [
    // Same as polyfills. Use this to indicate that the code handles missing APIs in a way other than polyfilling.
  ],
  // By default, TypeScript's type checker is run, to ensure that TypeScript errors don't prevent these checks from working.
  // It can be disabled to speed up the checks.
  "skipTypeCheck": true
}

To ignore a single API usage, add // @tsbc-ignore on the previous line. If an API is used in many places, wrap it in an internal module, or add it to the polyfills or ignore lists.

iainmerrick / ts-browser-compat Goto Github PK