# Декларация окружения

Как мы сказали в разделе [почему](https://igorfonin.gitbook.io/typescript-book-ru/) TypeScript:

> Основная цель разработки TypeScript состоит в том, чтобы позволить вам безопасно и легко использовать существующие Javascript библиотеки в TypeScript. TypeScript делает это посредством объявлений.

Декларация окружения позволяют вам безопасно использовать существующие популярные библиотеки JavaScript и постепенно переносить ваш проект с `JavaScript / CoffeeScript / Other-Compile-To-Js-Language` на TypeScript.

Научиться писать декларацию окружения для сторонних библиотек JavaScript - хорошая практика для написания аннотаций для TypeScript.

## Файл декларации

Вы можете использовать ключевое слово `declare`, чтобы сообщить TypeScript, что вы пытаетесь описать код, который уже существует в другом месте (например: код, написанный на JavaScript, CoffeeScript, среда такая как браузер или Node.js):

```typescript
foo = 123; // Error: 'foo' is not defined
```

против.

```typescript
declare var foo: any;
foo = 123; // allow
```

Вы можете поместить эти объявления в `.ts` или `.d.ts`. В вашем реальном проекте мы настоятельно рекомендуем поместить объявление в `.d.ts` (вы можете начать с файлов  `global.d.ts` или `vendor.d.ts` ).

Если файл имеет расширение `.d.ts`, это означает, что каждое объявление верхнего уровня должно начинаться с ключевого слова `declare`. Это гарантирует, что TypeScript не влияет на код. Автор должен проверить, что заявленный элемент существует во время выполнения.

{% hint style="info" %}

* Декларация окружения похожа на соглашение между вами и компилятором. Если вы попытаетесь использовать элемент без него во время выполнения, программа вылетит без предупреждения.
* Декларация окружения похожа на документацию. При изменении источника документация должна быть обновлена. Поэтому, если вы не декларацию окружения, когда во время выполнения возникает новое поведение, вы получите ошибку компиляции.
  {% endhint %}

## Переменные

Например, чтобы рассказать TypeScript о переменной `process`, вы можете написать:

```typescript
declare let process: any;
```

{% hint style="info" %}
Вам не нужно делать это для `process` , потому что он уже существует в файле [node.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/index.d.ts), поддерживаемом сообществом.
{% endhint %}

Это позволяет использовать `process` и успешно компилировать с помощью TypeScript:

```typescript
process.exit();
```

Мы рекомендуем использовать интерфейсы всякий раз, когда это возможно, например:

```typescript
interface Process {
  exit(code?: number): void;
}

declare let process: Process;
```

Это позволяет расширять глобальные переменные, но также позволяет TypeScript знать об изменениях в глобальных переменных. Например, в следующем примере добавляется функция `exitWithLogging` для обработки по мере необходимости:

```typescript
interface Process {
  exitWithLogging(code?: number): void;
}

process.exitWithLogging = function() {
  console.log('exiting');
  process.exit.apply(process, arguments);
};
```

Далее давайте разберемся с интерфейсами более подробно.