# Environment `env.browser`

Creates configuration objects with global symbols and linter rules for modules running in the browser. Adds well-known [browser globals](https://github.com/sindresorhus/globals), and forbids [confusing browser globals](https://github.com/facebook/create-react-app/tree/main/packages/confusing-browser-globals). Adds the following plugins and their recommended rules:

- [eslint-plugin-no-unsanitized](https://github.com/mozilla/eslint-plugin-no-unsanitized/)

## Signature

```ts
function browser(options: EnvBrowserOptions): ConfigArg
```

## Options

| Name | Type | Default | Description |
| - | - | - | - |
| `basePath` | `string` | `'.'` | Path to a sub directory to apply the environment preset to. |
| `files` | `Array<string\|string[]>` | _required_ | Glob patterns for source files to be included. Use embedded arrays for AND patterns. |
| `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
| `restricted` | `EnvRestrictedOptions` | `{}` | Settings for banned globals, imports, object properties, and syntax constructs (see below). |
| `rules` | `RulesConfig` | `{}` | Additional linter rules to be added to the configuration. |

### Option `restricted`

- Type: `EnvRestrictedOptions`
- Default: `{}`

This option allows to specify banned globals, imports, object properties, and syntax constructs. These restricted items will be set on top of the built-in restricted items of the environment preset, and will be passed to the respective ESLint core rules (see table below).

The option `restricted` is an object with the following properties:

| Name | Type | Default | Description | ESLint Rules |
| - | - | - | - | - |
| `globals` | `EnvRestrictedName[]` | `[]` | Banned global symbols. Each entry is an object with string properties `name` and `message`. | [`no-restricted-globals`](https://eslint.org/docs/latest/rules/no-restricted-globals) |
| `imports` | `EnvRestrictedName[]` | `[]` | Banned modules that must not be imported. Each entry is an object with string properties `name` and `message`. | [`no-restricted-imports`](https://eslint.org/docs/latest/rules/no-restricted-imports), [`no-restricted-modules`](https://eslint.org/docs/latest/rules/no-restricted-modules) |
| `properties` | `EnvRestrictedProperty[]` | `[]` | Banned object properties. Each entry is an object with string properties `object`, `property`, and `message`). | [`no-restricted-properties`](https://eslint.org/docs/latest/rules/no-restricted-properties) |
| `syntax` | `EnvRestrictedSyntax[]` | `[]` | Banned syntax constructs by [AST selectors](https://eslint.org/docs/latest/extend/selectors). Each entry is an object with string properties `selector` and `message`. | [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax) |
| `overrides` | `EnvRestrictedOverride[]` | `[]` | Overrides for specific subsets of files in the environment. Each entry is an object with the common properties `files` (required) and `ignores`, and the properties `globals`, `imports`, `properties`, and `syntax` to specify restricted items (see above). All restricted items of overrides will be merged with the common restricted items defined for the entire environment. | |

The environment `env.browser` already defines the following built-in restrictions:

| Type | Name | Description |
| - | - | - |
| Globals | [`isFinite`](https://devdocs.io/javascript/global_objects/isfinite) | Use [`Number.isFinite`](https://devdocs.io/javascript/global_objects/number/isfinite) instead. |
| | [`isNaN`](https://devdocs.io/javascript/global_objects/isnan) | Use [`Number.isNaN`](https://devdocs.io/javascript/global_objects/number/isnan) instead. |
| | [Confusing browser globals](https://github.com/facebook/create-react-app/tree/main/packages/confusing-browser-globals) | Globals such as `name` and `event` should not be used to catch typos in function parameters etc. |
| Syntax | TypeScript `public` class field modifier | Can be omitted (except for constructors of classes deriving from a class with protected constructor). |
| | TypeScript `private` class field modifier | Use native `#private` class fields. |
| | [TypeScript parameter properties](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties) | Use explicit class properties. |
| | Module exports of [TypeScript const enumerations](https://devdocs.io/typescript~5.1/enums#enums-at-compile-time) | Not compatible with bundlers running in isolated modules mode. |

## Example

```ts
// eslint.config.ts
import { defineConfig, env } from '@open-xchange/linter-presets/eslint'

export default defineConfig(

  // project configuration options
  { /* ... */ },

  // browser environment
  env.browser({
    files: ['src/**/*.{js,ts}'],
    restricted: {
      globals: [
        { name: '$', message: 'Explicitly import the `jquery` package.' },
      ],
      imports: [
        { name: 'underscore', message: 'Use the `lodash` package.' },
      ],
      properties: [
        { object: '_', property: 'flatten', message: 'Use native `Array::flat` instead.' },
      ],
      syntax: [
        { selector: 'ClassBody > StaticBlock', message: 'Static blocks not supported in all browsers.' },
      ],
      overrides: [
        {
          files: 'src/**/*.ts',
          properties: [
            { object: '$', property: 'Deferred', message: 'Use native promises in TypeScript code.' },
          ],
        },
      ],
    },
    rules: { /* ... */ },
  }),
)
```