@fluxwp/plugin-kit 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -30
- package/package.json +23 -6
package/README.md
CHANGED
|
@@ -1,98 +1,164 @@
|
|
|
1
1
|
# @fluxwp/plugin-kit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
shared runtime (React, React Query, i18next, `@fluxwp/ui`, `@fluxwp/graphql`) once per page, so your
|
|
6
|
-
bundle carries only your screens (a few KB).
|
|
3
|
+
[](https://www.npmjs.com/package/@fluxwp/plugin-kit)
|
|
4
|
+
[](#license)
|
|
7
5
|
|
|
8
|
-
|
|
6
|
+
**Build wp-admin screens for your WordPress plugin in React and TypeScript**, with typed GraphQL
|
|
7
|
+
(WPGraphQL) queries, persisted queries and server-side preloaded data. Your screens open inside the same
|
|
8
|
+
fast single-page admin shell as the [FluxWP](https://fluxwp.com) plugins: no page reload between screens,
|
|
9
|
+
light / dark theme, translations.
|
|
10
|
+
|
|
11
|
+
- **Tiny bundles.** React, React Query, i18next and the FluxWP UI kit come from a shared runtime that the
|
|
12
|
+
Flux GraphQL plugin loads once per page. A plugin screen is usually a few KB.
|
|
13
|
+
- **End-to-end types.** `flx-kit codegen` turns your `.graphql` operations into TypeScript types and
|
|
14
|
+
ready-to-use operation constants, checked against the site's schema.
|
|
15
|
+
- **Fast first paint.** PHP preloads the first query, so the screen renders without a spinner.
|
|
16
|
+
- **Vite preset.** `fluxScreens()` does the wiring: runtime imports, scoped CSS, code splitting.
|
|
17
|
+
|
|
18
|
+
Needs the **Flux GraphQL** plugin (`flx-graphql` 0.5 or newer) on the WordPress site.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
9
21
|
|
|
10
22
|
```sh
|
|
11
|
-
|
|
23
|
+
npm i -D @fluxwp/plugin-kit react @tanstack/react-query react-i18next typescript vite
|
|
24
|
+
# or: bun add -d … / pnpm add -D …
|
|
12
25
|
```
|
|
13
26
|
|
|
27
|
+
## Project layout
|
|
28
|
+
|
|
14
29
|
```
|
|
15
30
|
my-plugin/
|
|
16
|
-
my-plugin.php
|
|
31
|
+
my-plugin.php registers the screen and the persisted queries (below)
|
|
17
32
|
graphql/operations/FlxMyOrders.graphql
|
|
18
|
-
graphql/schema.graphql
|
|
19
|
-
screens/index.ts
|
|
33
|
+
graphql/schema.graphql your own GraphQL types, if the plugin registers any
|
|
34
|
+
screens/index.ts export const screens = { 'my-orders': () => import('./Orders') }
|
|
20
35
|
vite.config.ts
|
|
21
36
|
```
|
|
22
37
|
|
|
23
38
|
```ts
|
|
24
39
|
// vite.config.ts
|
|
25
40
|
import { fluxScreens } from '@fluxwp/plugin-kit/vite';
|
|
41
|
+
|
|
26
42
|
export default fluxScreens({ entry: 'my-plugin/screens/index.ts', outDir: 'my-plugin/assets/flux' });
|
|
27
43
|
```
|
|
28
44
|
|
|
45
|
+
```graphql
|
|
46
|
+
# my-plugin/graphql/operations/FlxMyOrders.graphql
|
|
47
|
+
query FlxMyOrders {
|
|
48
|
+
viewer { name }
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
29
52
|
```sh
|
|
30
|
-
flx-kit codegen my-plugin
|
|
31
|
-
vite build
|
|
53
|
+
npx flx-kit codegen my-plugin # → screens/generated/{types,operations}.ts + graphql/persisted-queries.json
|
|
54
|
+
npx vite build # → assets/flux/flux-screens.js (+ chunks, css, chunks.json)
|
|
32
55
|
```
|
|
33
56
|
|
|
34
|
-
##
|
|
57
|
+
## A screen
|
|
35
58
|
|
|
36
59
|
```tsx
|
|
60
|
+
// my-plugin/screens/Orders.tsx
|
|
37
61
|
import { useMemo } from 'react';
|
|
38
62
|
import { useTranslation } from 'react-i18next';
|
|
39
63
|
import { createGraphQLClient } from '@fluxwp/graphql';
|
|
40
64
|
import { FlxGraphQLProvider, useFlxQuery } from '@fluxwp/graphql/react';
|
|
41
65
|
import { useHost } from '@fluxwp/host';
|
|
66
|
+
import { Loading } from '@fluxwp/ui';
|
|
42
67
|
import { FlxMyOrders } from './generated/operations';
|
|
43
68
|
|
|
44
|
-
export function Orders() {
|
|
69
|
+
export default function Orders() {
|
|
45
70
|
const host = useHost();
|
|
46
71
|
const client = useMemo(() => createGraphQLClient({ api: host.client }), [host.client]);
|
|
47
|
-
return
|
|
72
|
+
return (
|
|
73
|
+
<FlxGraphQLProvider client={client} scope={host.scope}>
|
|
74
|
+
<Hello />
|
|
75
|
+
</FlxGraphQLProvider>
|
|
76
|
+
);
|
|
48
77
|
}
|
|
49
|
-
|
|
78
|
+
|
|
79
|
+
function Hello() {
|
|
50
80
|
const { t } = useTranslation('my');
|
|
51
|
-
const q = useFlxQuery(FlxMyOrders, {});
|
|
52
|
-
|
|
81
|
+
const q = useFlxQuery(FlxMyOrders, {}); // q.data is typed from the schema
|
|
82
|
+
if (!q.data) return <Loading />;
|
|
83
|
+
return <h1>{t('hello', { name: q.data.viewer?.name })}</h1>;
|
|
53
84
|
}
|
|
54
85
|
```
|
|
55
86
|
|
|
56
|
-
`screens/index.ts` may also export `resources` (`{ en: { my: {
|
|
87
|
+
`screens/index.ts` may also export `resources` (`{ en: { my: { hello: 'Hello {{name}}' } }, tr: { … } }`)
|
|
88
|
+
for i18next.
|
|
57
89
|
|
|
58
|
-
## PHP
|
|
90
|
+
## PHP side
|
|
59
91
|
|
|
60
92
|
```php
|
|
61
93
|
add_filter( 'flx_gql_persisted_manifests', function ( $m ) {
|
|
62
94
|
$m['my-plugin'] = __DIR__ . '/graphql/persisted-queries.json';
|
|
63
95
|
return $m;
|
|
64
96
|
} );
|
|
97
|
+
|
|
65
98
|
add_action( 'admin_menu', function () {
|
|
66
99
|
add_menu_page( 'Orders', 'Orders', 'read', 'my-orders', function () {
|
|
67
|
-
if ( function_exists( 'flx_admin_screen_render' ) && flx_admin_screen_render() )
|
|
68
|
-
|
|
100
|
+
if ( function_exists( 'flx_admin_screen_render' ) && flx_admin_screen_render() ) {
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
echo 'This screen needs the Flux GraphQL plugin.';
|
|
69
104
|
} );
|
|
70
105
|
if ( function_exists( 'flx_admin_screen' ) ) {
|
|
71
106
|
flx_admin_screen( 'my-orders', array(
|
|
72
107
|
'module' => 'my-orders',
|
|
73
108
|
'assets_dir' => __DIR__ . '/assets/flux/',
|
|
74
109
|
'assets_url' => plugin_dir_url( __FILE__ ) . 'assets/flux/',
|
|
75
|
-
'preload' => array( array( 'FlxMyOrders' ) ),
|
|
110
|
+
'preload' => array( array( 'FlxMyOrders' ) ), // first data ships with the page
|
|
76
111
|
) );
|
|
77
112
|
}
|
|
78
113
|
}, 20 );
|
|
79
114
|
```
|
|
80
115
|
|
|
81
|
-
Your own GraphQL types
|
|
82
|
-
|
|
83
|
-
|
|
116
|
+
### Your own GraphQL types
|
|
117
|
+
|
|
118
|
+
Register them in PHP with the Flux GraphQL kit (`flx_gql_type`, `flx_gql_query`, `flx_gql_mutation` on
|
|
119
|
+
`flx_gql_register`; every field declares a capability). To type-check your screens against them, export the
|
|
120
|
+
schema of a site with your plugin active and keep your part in the plugin:
|
|
84
121
|
|
|
85
122
|
```sh
|
|
86
123
|
wp flx-gql schema --output=schema.graphql --owners=owners.json
|
|
87
|
-
flx-kit schema-split schema.graphql owners.json my-plugin # → my-plugin/graphql/schema.graphql
|
|
124
|
+
npx flx-kit schema-split schema.graphql owners.json my-plugin # → my-plugin/graphql/schema.graphql
|
|
88
125
|
```
|
|
89
126
|
|
|
127
|
+
## CLI
|
|
128
|
+
|
|
129
|
+
| Command | Does |
|
|
130
|
+
|---|---|
|
|
131
|
+
| `flx-kit codegen <plugin-dir> [--check]` | Types, operation constants and `persisted-queries.json` for the plugin's operations (`--check`: fail if out of date, for CI) |
|
|
132
|
+
| `flx-kit schema-split <schema> <owners> <plugin-dir>` | Writes the plugin's own part of a site schema |
|
|
133
|
+
|
|
90
134
|
## Rules
|
|
91
135
|
|
|
92
136
|
- Import only what the runtime provides: `react`, `react/jsx-runtime`, `react-dom`, `react-dom/client`,
|
|
93
137
|
`@tanstack/react-query`, `i18next`, `react-i18next`, `@fluxwp/core`, `@fluxwp/tokens`, `@fluxwp/ui`,
|
|
94
|
-
`@fluxwp/graphql`, `@fluxwp/graphql/react`, `@fluxwp/host`.
|
|
95
|
-
|
|
96
|
-
-
|
|
138
|
+
`@fluxwp/graphql`, `@fluxwp/graphql/react`, `@fluxwp/host`. Anything else is bundled with your screens;
|
|
139
|
+
other `@fluxwp/*` imports fail the build.
|
|
140
|
+
- Operation names start with `Flx` (`FlxMyOrders`), one operation per file. Prefix screen ids with your
|
|
141
|
+
plugin (`acme-orders`).
|
|
142
|
+
- Your CSS is scoped under `.flux-root`; the `@fluxwp/ui` styles are already on the page.
|
|
143
|
+
|
|
144
|
+
Complete example plugin:
|
|
145
|
+
[`example/acme-hello`](https://github.com/FluxWP/FluxWP/tree/main/packages/plugin-kit/example/acme-hello).
|
|
146
|
+
|
|
147
|
+
## The FluxWP packages
|
|
148
|
+
|
|
149
|
+
| Package | What it is |
|
|
150
|
+
|---|---|
|
|
151
|
+
| [`@fluxwp/plugin-kit`](https://www.npmjs.com/package/@fluxwp/plugin-kit) | Build wp-admin React screens for your own WordPress plugin (Vite preset + `flx-kit` codegen) |
|
|
152
|
+
| [`@fluxwp/graphql`](https://www.npmjs.com/package/@fluxwp/graphql) | Typed GraphQL client and React hooks for Flux GraphQL (WPGraphQL) |
|
|
153
|
+
| [`@fluxwp/host`](https://www.npmjs.com/package/@fluxwp/host) | Host context of a screen: site client, user, locale |
|
|
154
|
+
| [`@fluxwp/ui`](https://www.npmjs.com/package/@fluxwp/ui) | React UI kit of FluxWP screens: Check, DatePicker, Modal, Icon … |
|
|
155
|
+
| [`@fluxwp/core`](https://www.npmjs.com/package/@fluxwp/core) | WordPress REST client, sign-in (OAuth PKCE, app passwords), accounts, i18n |
|
|
156
|
+
| [`@fluxwp/tokens`](https://www.npmjs.com/package/@fluxwp/tokens) | Design tokens: colours, spacing, radius, type, light / dark |
|
|
157
|
+
|
|
158
|
+
[FluxWP](https://fluxwp.com) is an open-source, all-in-one WordPress suite (donations, forms, e-commerce,
|
|
159
|
+
CRM, e-mail, AI, SEO) with a desktop and mobile app. Source:
|
|
160
|
+
[github.com/FluxWP/FluxWP](https://github.com/FluxWP/FluxWP). Questions and ideas: info@fluxwp.com.
|
|
161
|
+
|
|
162
|
+
## License
|
|
97
163
|
|
|
98
|
-
|
|
164
|
+
GPL-2.0-or-later
|
package/package.json
CHANGED
|
@@ -1,16 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fluxwp/plugin-kit",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Build wp-admin screens for
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Build wp-admin React screens for your WordPress plugin: Vite preset, typed GraphQL codegen, persisted queries, shared runtime.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"fluxwp",
|
|
7
|
+
"wordpress",
|
|
8
|
+
"typescript",
|
|
9
|
+
"wordpress-plugin",
|
|
10
|
+
"wp-admin",
|
|
11
|
+
"react",
|
|
12
|
+
"vite",
|
|
13
|
+
"vite-plugin",
|
|
14
|
+
"graphql",
|
|
15
|
+
"wpgraphql",
|
|
16
|
+
"codegen",
|
|
17
|
+
"cli",
|
|
18
|
+
"admin-ui"
|
|
19
|
+
],
|
|
20
|
+
"author": "FluxWP <info@fluxwp.com> (https://fluxwp.com)",
|
|
5
21
|
"type": "module",
|
|
6
22
|
"license": "GPL-2.0-or-later",
|
|
7
|
-
"homepage": "https://
|
|
23
|
+
"homepage": "https://github.com/FluxWP/FluxWP/tree/main/packages/plugin-kit#readme",
|
|
8
24
|
"repository": {
|
|
9
25
|
"type": "git",
|
|
10
26
|
"url": "git+https://github.com/FluxWP/FluxWP.git",
|
|
11
27
|
"directory": "packages/plugin-kit"
|
|
12
28
|
},
|
|
13
29
|
"bugs": {
|
|
30
|
+
"url": "https://github.com/FluxWP/FluxWP/issues",
|
|
14
31
|
"email": "info@fluxwp.com"
|
|
15
32
|
},
|
|
16
33
|
"exports": {
|
|
@@ -41,10 +58,10 @@
|
|
|
41
58
|
],
|
|
42
59
|
"sideEffects": false,
|
|
43
60
|
"dependencies": {
|
|
44
|
-
"@fluxwp/core": "^0.4.
|
|
61
|
+
"@fluxwp/core": "^0.4.6",
|
|
45
62
|
"@fluxwp/graphql": "^0.4.0",
|
|
46
|
-
"@fluxwp/tokens": "^0.4.
|
|
47
|
-
"@fluxwp/ui": "^0.3.
|
|
63
|
+
"@fluxwp/tokens": "^0.4.1",
|
|
64
|
+
"@fluxwp/ui": "^0.3.3",
|
|
48
65
|
"@graphql-codegen/core": "^7.0.0",
|
|
49
66
|
"@graphql-codegen/typescript-operations": "^7.0.1",
|
|
50
67
|
"@vitejs/plugin-react": "^6.1.2",
|