Skip to content

Commit

Permalink
docs(importing.md): emphasize new operator imports
Browse files Browse the repository at this point in the history
  • Loading branch information
jakovljevic-mladen committed Nov 16, 2021
1 parent fdc7938 commit 4691714
Showing 1 changed file with 51 additions and 26 deletions.
77 changes: 51 additions & 26 deletions docs_app/content/guide/importing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,53 @@
There are different ways you can {@link guide/installation install} RxJS. Using/importing RxJS depends on
the used RxJS version, but also depends on the used installation method.

# Export sites
[Pipeable operators](https://v6.rxjs.dev/guide/v6/pipeable-operators) were introduced in RxJS version
5.5. This enabled all operators to be exported from a single place. This new export site was introduced
with RxJS version 6 where all pipeable operators could have been imported from `'rxjs/operators'`. For
example, `import { map } from 'rxjs/operators'`.

RxJS v7 exports 6 different locations out of which you can import what you need. Those are:
# New in RxJS v7.2.0

<span class="informal">**With RxJS v7.2.0, most operators have been moved to `{@link api#index 'rxjs'}`
export site. This means that the preferred way to import operators is from `'rxjs'`, while
`'rxjs/operators'` export site has been deprecated.**</span>

- `{@link api#index 'rxjs'}` (for example: `import { of } from 'rxjs'`)
- `{@link api#operators 'rxjs/operators'}` (for example: `import { map } from 'rxjs/operators'`)
- `{@link api#ajax 'rxjs/ajax'}` (for example: `import { ajax } from 'rxjs/ajax'`)
- `{@link api#fetch 'rxjs/fetch'}` (for example: `import { fromFetch } from 'rxjs/fetch'`)
- `{@link api#webSocket 'rxjs/webSocket'}` (for example: `import { webSocket } from 'rxjs/webSocket'`)
- `{@link api#testing 'rxjs/testing'}` (for example: `import { TestScheduler } from 'rxjs/testing'`)
For example, instead of using:

A new way of importing {@link guide/operators operators} is introduced with RxJS v7.2.0.
```ts
import { map } from 'rxjs/operators';
```

# What's changed in RxJS v7.2.0?
**the preferred way** is to use:

[Pipeable operators](https://v6.rxjs.dev/guide/v6/pipeable-operators) were introduced in RxJS version
5.5. This enabled all operators to be exported from a single place. This new export site was introduced
with RxJS version 6 where all pipeable operators could have been imported from `'rxjs/operators'`. For
example, `import { map } from 'rxjs/operators'`.
```ts
import { map } from 'rxjs';
```

Although the old way of importing operators is still active, it will be removed in one of the next major
versions.

Click {@link #how-to-migrate here to see} how to migrate.

With RxJS v7.2.0, most operators have been moved to `{@link api#index 'rxjs'}` export site. This means
that preferred way to import operators is from `'rxjs'`.
# Export sites

RxJS v7 exports 6 different locations out of which you can import what you need. Those are:

For example, instead of using: `import { map } from 'rxjs/operators'`, the preferred way is to use:
`import { map } from 'rxjs'`. Although old way of importing operators is still active, it will soon
become deprecated.
- `{@link api#index 'rxjs'}` - for example: `import { of } from 'rxjs';`
- `{@link api#operators 'rxjs/operators'}` - for example: `import { map } from 'rxjs/operators';`
- `{@link api#ajax 'rxjs/ajax'}` - for example: `import { ajax } from 'rxjs/ajax';`
- `{@link api#fetch 'rxjs/fetch'}` - for example: `import { fromFetch } from 'rxjs/fetch';`
- `{@link api#webSocket 'rxjs/webSocket'}` - for example: `import { webSocket } from 'rxjs/webSocket';`
- `{@link api#testing 'rxjs/testing'}` - for example: `import { TestScheduler } from 'rxjs/testing';`

## What stayed in `'rxjs/operators'`?
## How to migrate?

Only couple of old and mostly deprecated operators have stayed in the `'rxjs/operators'`. Those
operators are now mostly deprecated and most of them have their either static operator substitution
or are kept as operators, but have a new name so that they are different to their static creation
counter-part (usually ending with `With`). Those are:
While nothing has been removed from `'rxjs/operators'`, it is strongly recommended doing the operator
imports from `'rxjs'`. Almost all operator function exports have been moved to `'rxjs'`, but only a
couple of old and deprecated operators have stayed in the `'rxjs/operators'`. Those operator functions
are now mostly deprecated and most of them have their either static operator substitution or are kept as
operators, but have a new name so that they are different to their static creation counter-part (usually
ending with `With`). Those are:

| `'rxjs/operators'` Operator | Replace With Static Creation Operator | Replace With New Operator Name |
| ------------------------------------------------------- | ------------------------------------- | ------------------------------ |
Expand All @@ -47,15 +61,26 @@ counter-part (usually ending with `With`). Those are:
| [`race`](/api/operators/race) | {@link race} | {@link raceWith} |
| [`zip`](/api/operators/zip) | {@link zip} | {@link zipWith} |

For example, usage of a static creation {@link merge} operator:
For example, the old and deprecated way of using [`merge`](/api/operators/merge) from `'rxjs/operators'`
is:

```ts
import { merge } from 'rxjs/operators';

a$.pipe(merge(b$)).subscribe();
```

But this should be avoided and replaced with one of the next two examples.

For example, this could be replaced by using a static creation {@link merge} function:

```ts
import { merge } from 'rxjs';

merge(a$, b$).subscribe();
```

could be written as (using a pipeable operator):
Or it could be written using a pipeable {@link mergeWith} operator:

```ts
import { mergeWith } from 'rxjs';
Expand Down

0 comments on commit 4691714

Please sign in to comment.