Skip to content

Commit d0f444e

Browse files
committed
docs: complete the samples in the ship-a-plugin guide
The guide now says apps install the devtools package themselves, since it is an optional peer. flagsView is said to live in the same file, both tool schemas take the optional page argument as the example does, the FeatureFlags service is shown with its store, and the Vite sample imports and calls analog().
1 parent 2aed246 commit d0f444e

1 file changed

Lines changed: 32 additions & 9 deletions

File tree

‎apps/docs/src/content/guides/ship-a-plugin.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ import {registerPangularPlugin, type PangularPagePlugin} from '@pangular-inspect
7676
import {FLAGS_PLUGIN_ID, FLAGS_PLUGIN_VERSION} from './ids.ts';
7777
import type {FlagStore} from './index.ts';
7878

79+
// flagsView(store) builds the PluginView; it is defined just above this in the same file.
7980
export function flagsPangularPlugin(store: FlagStore): PangularPagePlugin {
8081
return {
8182
id: FLAGS_PLUGIN_ID,
@@ -103,7 +104,7 @@ export function registerFlagsPangularPlugin(store: FlagStore): () => void {
103104
}
104105
```
105106

106-
`flagsView()` returns a stats section and a table of flags, and lists the `reset` action while a flag is overridden. An error a page action throws reaches the agent as the tool's answer. The [sections table](./write-a-plugin.md#sections) lists every section kind.
107+
`flagsView()`, in the same file, returns a stats section and a table of flags, and lists the `reset` action while a flag is overridden. An error a page action throws reaches the agent as the tool's answer. The [sections table](./write-a-plugin.md#sections) lists every section kind.
107108

108109
Keep the plugin id and version in a file both entry points import (`src/ids.ts` in the example), so the page plugin and the server plugin always match.
109110

@@ -116,6 +117,10 @@ The server plugin adds agent tools over what the page reports. A tool that runs
116117
import {definePangularServerPlugin} from '@pangular-inspector/devtools/plugin';
117118
import {FLAGS_PLUGIN_ID, FLAGS_PLUGIN_VERSION} from './ids.ts';
118119

120+
const PAGE = {
121+
type: 'string',
122+
description: 'Page id, when more than one tab reports (see pangular:list-pages).',
123+
};
119124
const pageArg = (args: Record<string, unknown>) =>
120125
typeof args['page'] === 'string' ? args['page'] : undefined;
121126

@@ -127,6 +132,7 @@ export const flagsServerPlugin = definePangularServerPlugin({
127132
{
128133
name: 'flags',
129134
description: 'Every flag in the feature flag store on the running page.',
135+
inputSchema: {type: 'object', properties: {page: PAGE}},
130136
handler: (args, ctx) => {
131137
const page = ctx.page(pageArg(args));
132138
if (!page?.view) return 'No page runs the feature flag store. Open the app in a browser.';
@@ -139,7 +145,7 @@ export const flagsServerPlugin = definePangularServerPlugin({
139145
description: 'Turn one flag on or off on the running page until it reloads.',
140146
inputSchema: {
141147
type: 'object',
142-
properties: {name: {type: 'string'}, value: {type: 'boolean'}},
148+
properties: {name: {type: 'string'}, value: {type: 'boolean'}, page: PAGE},
143149
required: ['name', 'value'],
144150
},
145151
handler: async (args, ctx) => {
@@ -160,7 +166,13 @@ The tools register as `pangular:plugin:feature-flags:flags` and `pangular:plugin
160166

161167
## Use it in an app
162168

163-
Tell the apps that use your library to make two changes.
169+
Your library lists `@pangular-inspector/devtools` as an optional peer dependency, so an app that wants the tab installs it as its own development dependency first:
170+
171+
```bash
172+
npm install -D @pangular-inspector/devtools
173+
```
174+
175+
Then tell the apps that use your library to make two changes.
164176

165177
<ngmd-workflow>
166178
<ngmd-step title="Register the page plugin in development">
@@ -179,10 +191,23 @@ import {isPlatformBrowser} from '@angular/common';
179191
import {
180192
DestroyRef,
181193
PLATFORM_ID,
194+
Service,
182195
inject,
183196
provideAppInitializer,
184197
type EnvironmentProviders,
185198
} from '@angular/core';
199+
import {createFlagStore} from 'pangular-plugin-example';
200+
201+
/** The demo's flags, kept in the example library's store. */
202+
@Service()
203+
export class FeatureFlags {
204+
readonly store = createFlagStore({
205+
'promo-banner': {
206+
default: false,
207+
description: 'Shows the free shipping banner on the home page.',
208+
},
209+
});
210+
}
186211

187212
export function provideFeatureFlagsPangularPlugin(): EnvironmentProviders {
188213
return provideAppInitializer(() => {
@@ -198,19 +223,17 @@ export function provideFeatureFlagsPangularPlugin(): EnvironmentProviders {
198223
}
199224
```
200225

201-
`FeatureFlags` is the demo's service that holds the store, in the same file. Add `provideFeatureFlagsPangularPlugin()` to the app's providers. Then pass the server plugin to the Vite plugin:
226+
`FeatureFlags` is the demo's service that holds the store; the real one also turns store changes into a signal for templates. Add `provideFeatureFlagsPangularPlugin()` to the app's providers. Then pass the server plugin to the Vite plugin:
202227

203-
```ts {3,9}
228+
```ts {4,8}
204229
// examples/analog/vite.config.ts
230+
import analog from '@analogjs/platform';
205231
import pangular from '@pangular-inspector/devtools/vite';
206232
import {flagsServerPlugin} from 'pangular-plugin-example/pangular-server';
207233
import {defineConfig} from 'vite';
208234

209235
export default defineConfig(() => ({
210-
plugins: [
211-
// analog(...) and other plugins
212-
pangular({serverPlugins: [flagsServerPlugin]}),
213-
],
236+
plugins: [analog(), pangular({serverPlugins: [flagsServerPlugin]})],
214237
}));
215238
```
216239

0 commit comments

Comments
 (0)