You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Output TypeScript declaration files (`.d.ts`) from package sources and expose them with published packages.
- Upgrade to `typescript@3.8`.
- Add bin for typechecking changed packages.
- Remove `lint-types` script, replaced by `build:package-types`.
- Restructure TypeScript configuration:
- One base `tsconfig.base.json` that packages extend. This is not a project, it's only for extension.
- A root `tsconfig.json` that references all typed packages.
- Typed packages output their types at `build-types` and expose them in the published package.
- Use _project references_ to work within the monorepo.
See https://www.typescriptlang.org/docs/handbook/project-references.html
- Fix/improve some type issues.
TypeScript declaration files will be managed via `tsc --build`, the TypeScript compiler build tool for composite projects. `tsc` will manage determine the correct order to build packages so that dependencies are satisfied and rebuild only when necessary.
Additional packages can opt-in to typing by (this is documented in a new section in `packages/README.md`):
- Adding `tsconfig.json` in their package directory.
- Updating their `package.json` to point to the types: `{ "types": "build-types" }`.
- Adding a reference to the root `tsconfig.json`.
This assumes that your code is located in the `src` folder and will be transpiled with `Babel`.
40
38
2. `.npmrc` file which disables creating `package-lock.json` file for the package:
41
-
```
42
-
package-lock=false
43
-
```
39
+
```
40
+
package-lock=false
41
+
```
44
42
3. `README.md` file containing at least:
45
-
- Package name
46
-
- Package description
47
-
- Installation details
48
-
- Usage example
49
-
- `Code is Poetry` logo (`<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>`)
43
+
- Package name
44
+
- Package description
45
+
- Installation details
46
+
- Usage example
47
+
- `Code is Poetry` logo (`<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>`)
50
48
51
49
## Managing Dependencies
52
50
@@ -57,7 +55,7 @@ There are two types of dependencies that you might want to add to one of the exi
57
55
Production dependencies are stored in the `dependencies` section of the package’s `package.json` file.
58
56
59
57
#### Adding New Dependencies
60
-
58
+
61
59
The simplest way to add a production dependency to one of the packages is to run a very convenient [lerna add](https://github.com/lerna/lerna/tree/master/commands/add#readme) command from the root of the project.
62
60
63
61
_Example:_
@@ -91,9 +89,10 @@ Next, you need to run `npm install` in the root of the project to ensure that `p
91
89
#### Updating Existing Dependencies
92
90
93
91
This is the most confusing part of working with [lerna] which causes a lot of hassles for contributors. The most successful strategy so far is to do the following:
94
-
1. First, remove the existing dependency as described in the previous section.
95
-
2. Next, add the same dependency back as described in the first section of this chapter. This time it wil get the latest version applied unless you enforce a different version explicitly.
96
-
92
+
93
+
1. First, remove the existing dependency as described in the previous section.
94
+
2. Next, add the same dependency back as described in the first section of this chapter. This time it wil get the latest version applied unless you enforce a different version explicitly.
95
+
97
96
### Development Dependencies
98
97
99
98
In contrast to production dependencies, development dependencies shouldn't be stored in individual WordPress packages. Instead they should be installed in the project's `package.json` file using the usual `npm install` command. In effect, all development tools are configured to work with every package at the same time to ensure they share the same characteristics and integrate correctly with each other.
@@ -119,16 +118,16 @@ _Example:_
119
118
120
119
### Bug Fix
121
120
122
-
- Fixed an off-by-one error with the `sum` function.
121
+
-Fixed an off-by-one error with the `sum` function.
123
122
```
124
123
125
124
There are a number of common release subsections you can follow. Each is intended to align to a specific meaning in the context of the [Semantic Versioning (`semver`) specification](https://semver.org/) the project adheres to. It is important that you describe your changes accurately, since this is used in the packages release process to help determine the version of the next release.
126
125
127
-
- "Breaking Change" - A backwards-incompatible change which requires specific attention of the impacted developers to reconcile (requires a major version bump).
128
-
- "New Feature" - The addition of a new backwards-compatible function or feature to the existing public API (requires a minor verison bump).
129
-
- "Enhancement" - Backwards-compatible improvements to existing functionality (requires a minor version bump).
130
-
- "Bug Fix" - Resolutions to existing buggy behavior (requires a patch version bump).
131
-
- "Internal" - Changes which do not have an impact on the public interface or behavior of the module (requires a patch version bump).
126
+
-"Breaking Change" - A backwards-incompatible change which requires specific attention of the impacted developers to reconcile (requires a major version bump).
127
+
-"New Feature" - The addition of a new backwards-compatible function or feature to the existing public API (requires a minor verison bump).
128
+
-"Enhancement" - Backwards-compatible improvements to existing functionality (requires a minor version bump).
129
+
-"Bug Fix" - Resolutions to existing buggy behavior (requires a patch version bump).
130
+
-"Internal" - Changes which do not have an impact on the public interface or behavior of the module (requires a patch version bump).
132
131
133
132
While other section naming can be used when appropriate, it's important that are expressed clearly to avoid confusion for both the packages releaser and third-party consumers.
134
133
@@ -190,5 +189,61 @@ npm run publish:legacy
190
189
191
190
This is usually necessary when adding bug fixes or security patches to the earlier versions of WordPress.
192
191
192
+
## TypeScript
193
+
194
+
The [TypeScript](http://www.typescriptlang.org/) language is a typed superset of JavaScript that compiles to plain JavaScript.
195
+
Gutenberg does not use the TypeScript language, however TypeScript has powerful tooling that can be applied to JavaScript projects.
196
+
197
+
Gutenberg uses TypeScript for several reasons, including:
- Type system can detect some issues and lead to more robust software.
201
+
- Type declarations can be produced to allow other projects to benefit from these advantages as well.
202
+
203
+
### Using TypeScript
204
+
205
+
Gutenberg uses TypeScript by running the TypeScript compiler (`tsc`) on select packages.
206
+
These packages benefit from type checking and produced type declarations in the published packages.
207
+
208
+
To opt-in to TypeScript tooling, packages should include a `tsconfig.json` file in the package root and add an entry to the root `tsconfig.json` references.
209
+
The changes will indicate that the package has opted-in and will be included in the TypeScript build process.
210
+
211
+
A `tsconfig.json` file should look like the following (comments are not necessary):
212
+
213
+
```jsonc
214
+
{
215
+
// Extends a base configuration common to most packages
216
+
"extends":"../../tsconfig.base.json",
217
+
218
+
// Options for the TypeScript compiler
219
+
// We'll usually set our `rootDir` and `declarationDir` as follows, which is specific
220
+
// to each project.
221
+
"compilerOptions": {
222
+
"rootDir":"src",
223
+
"declarationDir":"build-types"
224
+
},
225
+
226
+
// Which source files should be included
227
+
"include": [ "src/**/*" ],
228
+
229
+
// Other WordPress package dependencies that have opted-in to TypeScript should be listed
230
+
// here. In this case, our package depends on `@wordpress/dom-ready`.
231
+
"references": [ { "path":"../dom-ready" } ]
232
+
}
233
+
```
234
+
235
+
Type declarations will be produced in the `build-types` which should be included in the published package.
236
+
For consumers to use the published type declarations, we'll set the `types` field in `package.json`:
237
+
238
+
```json
239
+
{
240
+
"main": "build/index.js",
241
+
"main-module": "build-module/index.js",
242
+
"types": "build-types"
243
+
}
244
+
```
245
+
246
+
Ensure that the `build-types` directory will be included in the published package, for example if a `files` field is declared.
0 commit comments