@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.
Files changed (2) hide show
  1. package/README.md +96 -30
  2. package/package.json +23 -6
package/README.md CHANGED
@@ -1,98 +1,164 @@
1
1
  # @fluxwp/plugin-kit
2
2
 
3
- Add wp-admin React screens to any WordPress plugin, on the same shell as FluxWP's own screens, with typed
4
- GraphQL operations. Needs the **Flux GraphQL** plugin (0.5+) on the site: it serves GraphQL and loads the
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
+ [![npm](https://img.shields.io/npm/v/@fluxwp/plugin-kit)](https://www.npmjs.com/package/@fluxwp/plugin-kit)
4
+ [![license](https://img.shields.io/npm/l/@fluxwp/plugin-kit)](#license)
7
5
 
8
- ## Setup
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
- bun add -d @fluxwp/plugin-kit react @tanstack/react-query react-i18next typescript vite
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 flx_admin_screen() + flx_gql_persisted_manifests (below)
31
+ my-plugin.php registers the screen and the persisted queries (below)
17
32
  graphql/operations/FlxMyOrders.graphql
18
- graphql/schema.graphql your own types, if the plugin registers any (flx-kit schema-split)
19
- screens/index.ts export const screens = { 'my-orders': () => import('./Orders') … }
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 # → my-plugin/screens/generated/{types,operations}.ts + graphql/persisted-queries.json
31
- vite build # → my-plugin/assets/flux/flux-screens.js (+ chunks, css, chunks.json)
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
- ## Screen
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 <FlxGraphQLProvider client={client} scope={host.scope}><List /></FlxGraphQLProvider>;
72
+ return (
73
+ <FlxGraphQLProvider client={client} scope={host.scope}>
74
+ <Hello />
75
+ </FlxGraphQLProvider>
76
+ );
48
77
  }
49
- function List() {
78
+
79
+ function Hello() {
50
80
  const { t } = useTranslation('my');
51
- const q = useFlxQuery(FlxMyOrders, {}); // typed from the schema
52
- return <h1>{t('title')} ({q.data?.flxMyOrders.totalCount ?? '…'})</h1>;
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: {…} }, tr: { my: {…} } }`) for i18next.
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() ) return;
68
- echo 'Flux GraphQL is needed for this screen.';
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' ) ), // first data comes with the page
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 are registered in PHP with the kit (`flx_gql_type`, `flx_gql_query` … on
82
- `flx_gql_register`). To type-check against them, export the site's schema with your plugin active and keep
83
- your part in the plugin:
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`. Other `@fluxwp/*` imports fail the build.
95
- - Operation names start with `Flx`, one operation per file; screen ids are unique (prefix them).
96
- - Your CSS is scoped under `.flux-root`; `@fluxwp/ui` styles are already on the page.
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
- Example plugin: [`example/acme-hello`](https://github.com/FluxWP/FluxWP/tree/main/packages/plugin-kit/example).
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.0",
4
- "description": "Build wp-admin screens for any WordPress plugin on the Flux runtime (Flux GraphQL 0.5+): Vite preset, GraphQL codegen, persisted queries.",
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://fluxwp.com",
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.5",
61
+ "@fluxwp/core": "^0.4.6",
45
62
  "@fluxwp/graphql": "^0.4.0",
46
- "@fluxwp/tokens": "^0.4.0",
47
- "@fluxwp/ui": "^0.3.2",
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",