Skip to content

Commit f4fbdae

Browse files
committed
Update README.md
1 parent 395896f commit f4fbdae

File tree

1 file changed

+42
-20
lines changed

1 file changed

+42
-20
lines changed

packages/core-js-types/README.md

Lines changed: 42 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
![logo](https://user-images.githubusercontent.com/2213682/146607186-8e13ddef-26a4-4ebf-befd-5aac9d77c090.png)
2-
This package contains types for global & pure versions of `core-js`.
3-
Although `core-js` is a polyfill library for the JavaScript, the built-in TypeScript types are not sufficient.
2+
3+
This package contains types for the global and pure versions of `core-js`.
4+
Although `core-js` is a JavaScript standard library polyfill, the built-in TypeScript types are often not sufficient.
45
Additional types are needed for:
5-
- features that are already in JavaScript, but not yet in TypeScript’s standard types;
6+
- features that are already in JavaScript but not yet in TypeScript’s standard types;
67
- proposals, including those already implemented in JavaScript engines;
78
- explicit imports of features from the pure version.
89

9-
It is shipped as a separate package, because we cannot guarantee stable behavior,
10-
primarily with upcoming minor TypeScript releases.
10+
It is shipped as a separate package because we cannot guarantee stable behavior with future TypeScript releases, including minor ones.
1111

1212
# Installation
13-
`npm install --save @core-js/[email protected]`
13+
```bash
14+
npm install --save @core-js/[email protected]
15+
```
1416

1517
# Usage
1618
Add to your `tsconfig.json`:
@@ -27,15 +29,16 @@ or import it directly in your files:
2729
```ts
2830
import '@core-js/types';
2931
```
30-
`@core-js/types` includes all types and entry points for the global version, but it is recommended to select only the subset you actually use instead.
32+
`@core-js/types` includes all types and entry points for the global version, but it is recommended to select only the subset you actually use.
3133

3234
## Usage of subsets
33-
There are 4 types of subset:
34-
- `@core-js/types/actual` - types for all actual features, including stable ECMAScript, web standards and stage 3 ECMAScript proposals
35-
- `@core-js/types/es` - types for stable ECMAScript features only
36-
- `@core-js/types/stable` - types for stable ECMAScript and web standards features
37-
- `@core-js/types/full` - types for all features, including proposals
38-
You can import them the same way as the main package, for example, to use stable version, add this to your `tsconfig.json`:
35+
There are four main subsets:
36+
- `@core-js/types/actual` - types for all actual features, including stable ECMAScript, web standards and Stage 3 ECMAScript proposals;
37+
- `@core-js/types/es` - types for stable ECMAScript features only;
38+
- `@core-js/types/stable` - types for stable ECMAScript and web standards features;
39+
- `@core-js/types/full` - types for all features, including proposals.
40+
41+
You can import them the same way as the main package. For example, to use only the stable subset, add this to your `tsconfig.json`:
3942
```json
4043
{
4144
"compilerOptions": {
@@ -50,6 +53,25 @@ or import it directly in your files:
5053
import '@core-js/types/stable';
5154
```
5255

56+
## Usage of specific features
57+
If you need types only for specific features, you can import them like this:
58+
```json
59+
{
60+
"compilerOptions": {
61+
"types": [
62+
"@core-js/types/proposals/array-unique",
63+
"@core-js/types/web/atob-btoa"
64+
]
65+
}
66+
}
67+
```
68+
or import them directly in your files:
69+
```ts
70+
import '@core-js/types/proposals/array-unique';
71+
import '@core-js/types/web/atob-btoa';
72+
```
73+
For a full list of available features, see the [documentation](https://core-js.io/v4/docs/).
74+
5375
# Types for the pure version
5476
## Base usage
5577
Add this to your `tsconfig.json`:
@@ -62,16 +84,15 @@ Add this to your `tsconfig.json`:
6284
}
6385
}
6486
```
65-
then, when you import from the pure entry points, the corresponding types are picked up automatically:
87+
Then, when you import from the pure entry points, the corresponding types are picked up automatically:
6688
```ts
6789
import $findLast from '@core-js/pure/full/array/find-last';
6890

6991
$findLast([1, 3, 4, 2], v => v > 2); // => 4
7092
```
7193

72-
## Namespace usage
73-
If you need to use multiple methods from the same namespace, you can add `@core-js/types/pure` to `tsconfig.json`
74-
and import the entire namespace instead:
94+
## Namespace usage in the pure version
95+
If you need to use multiple methods from the same namespace, you can add `@core-js/types/pure` to `tsconfig.json` and import the entire namespace:
7596
```ts
7697
import $array from '@core-js/pure/full/array';
7798

@@ -80,13 +101,14 @@ $array.flatMap([1, 2, 3], x => [x, x * 2]);
80101
```
81102

82103
# DOM types
83-
A part of the global types for web standards work correctly only with the DOM lib.
84-
You need to add DOM types to the `lib` section of your `tsconfig.json`, for example:
104+
Some of the global types for web standards work correctly only with the DOM lib.
105+
You need to add DOM types to the `lib` section of your `tsconfig.json` in addition to `@core-js/types`. For example:
85106
```json
86107
{
87108
"compilerOptions": {
109+
"types": ["@core-js/types"],
88110
"lib": ["esnext", "dom"]
89111
}
90112
}
91113
```
92-
In the `pure` version you can use it without adding DOM lib
114+
In the pure version, you can use these types without adding the DOM lib.

0 commit comments

Comments
 (0)