Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Documentation]: Minor updates in Private APIs #47953

Merged
merged 1 commit into from
Feb 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/contributors/code/coding-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ Each `@wordpress` package wanting to privately access or expose experimental API
do so by opting-in to `@wordpress/private-apis`:

```js
// In packages/block-editorwordpress/private-apis.js:
// In packages/block-editor/private-apis.js:
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
export const { lock, unlock } =
__dangerousOptInToUnstableAPIsOnlyForCoreModules(
Expand Down Expand Up @@ -366,6 +366,7 @@ const {
Remember to always register the private actions and selectors on the **registered** store.

Sometimes that's easy:

```js
export const store = createReduxStore( STORE_NAME, storeConfig() );
// `register` uses the same `store` object created from `createReduxStore`.
Expand Down
20 changes: 9 additions & 11 deletions packages/private-apis/README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# Experiments
# Private APIs

`@wordpress/private-apis` enables sharing private `__experimental` APIs across `@wordpress` packages without
`@wordpress/private-apis` enables sharing private `__experimental` APIs across `@wordpress` packages without
[publicly exposing them to WordPress extenders](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#respond).

## Getting started

Every `@wordpress` package wanting to privately access or expose experimental APIs must opt-in to `@wordpress/private-apis`:

```js
// In packages/block-editorwordpress/private-apis.js:
// In packages/block-editor/private-apis.js:
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
export const { lock, unlock } =
__dangerousOptInToUnstableAPIsOnlyForCoreModules(
'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
'@wordpress/block-editor' // Name of the package calling __dangerousOptInToUnstableAPIsOnlyForCoreModules,
// (not the name of the package whose APIs you want to access)
// (not the name of the package whose APIs you want to access)
);
```

Each package may only opt in once. The function name communicates that plugins are not supposed to use it.

The function will throw an error if the following conditions are not met:

1. The first argument must exactly match the required consent string: `'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.'`.
1. The first argument must exactly match the required consent string: `'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.'`.
2. The second argument must be a known `@wordpress` package that hasn't yet opted into `@wordpress/private-apis`

Once the opt-in is complete, the obtained `lock()` and `unlock()` utilities enable hiding `__experimental` APIs from the naked eye:
Expand Down Expand Up @@ -60,17 +60,15 @@ import { lock } from './private-apis';

export const experiments = {};
/* Attach private data to the exported object */
lock(experiments, {
__experimentalFunction: function() {},
});
lock( experiments, {
__experimentalFunction: function () {},
} );

// In packages/package2/index.js:
import { experiments } from '@wordpress/package1';
import { unlock } from './private-apis';

const {
__experimentalFunction
} = unlock( experiments );
const { __experimentalFunction } = unlock( experiments );
```

## Shipping experimental APIs
Expand Down