Skip to content
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 apps/docs/src/content/contributing/demo-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ It listens on port 4000, or on `PORT` when set.
- API routes under `src/server/routes/api/v1`, with method suffixes such as `index.get.ts` and `index.post.ts`, and a timing middleware.
- Markdown content under `src/content/blog` and `src/content/docs`.
- Prerendered routes listed in `vite.config.ts`, and `/dashboard` as client only (`ssr: false`).
- A **Feature flags** tab from the example plugin package `examples/pangular-plugin-example`, with its `promo-banner` and `blog-teaser` flags on the home page. See [Ship a plugin from a library](../guides/ship-a-plugin.md).

### Run Analog in development

Expand All @@ -127,7 +128,7 @@ The script builds the devtools package, then starts the Vite dev server. That de

### Type-check the Analog demo

`pnpm typecheck` runs `ngc -p examples/analog/tsconfig.app.json --noEmit`, so CI type-checks the demo's pages, templates, loaders, API routes and middleware. The demo resolves `@pangular-inspector/devtools` to the package source, which imports with `.ts` extensions, so `tsconfig.app.json` sets `rewriteRelativeImportExtensions`.
`pnpm typecheck` runs `ngc -p examples/analog/tsconfig.app.json --noEmit`, so CI type-checks the demo's pages, templates, loaders, API routes and middleware. The demo resolves `@pangular-inspector/devtools` to the package source, which imports with `.ts` extensions, so `tsconfig.app.json` sets `rewriteRelativeImportExtensions`. It also includes the sources of `examples/pangular-plugin-example`, which the demo imports as TypeScript, so the Analog compiler builds them.

### Build and preview

Expand Down
246 changes: 246 additions & 0 deletions apps/docs/src/content/guides/ship-a-plugin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
---
title: Ship a plugin from a library
description: Package a Pangular tab and its agent tools with your library, so every app that uses the library gets them.
---

<ngmd-hero title="Ship a plugin from a library" gradient>
Publish the tab with your package. An app adds one provider and one Vite option, and the panel shows your library's state.
</ngmd-hero>

# Ship a plugin from a library

[Write a plugin](./write-a-plugin.md) builds a plugin inside one app. This guide puts the same parts in a library package, so the apps that install the library get its tab without writing one.

The repository has a working example: `examples/pangular-plugin-example`, a small feature flag store with its own **Feature flags** tab and two agent tools. The Analog demo (`examples/analog`) uses it. The code on this page comes from those two folders.

## Lay out the package

Keep the devtools code out of the library's main entry point. An app that never loads Pangular Inspector then never loads the plugin either.

| Entry point | File | What it holds |
| ------------------- | ------------------------ | --------------------------------------------------------------- |
| `.` | `src/index.ts` | The library itself. It imports nothing from Pangular Inspector. |
| `./pangular` | `src/pangular.ts` | The page plugin and a `register…` helper. Runs in the browser. |
| `./pangular-server` | `src/pangular-server.ts` | The server plugin with the agent tools. Runs in Node. |

Both devtools entry points import `@pangular-inspector/devtools/plugin` only. That entry point is small and imports neither the overlay nor the server.

Declare the devtools as an optional peer dependency, so apps without them install the library without a warning. The example's `package.json`:

```json
{
"name": "pangular-plugin-example",
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./pangular": "./src/pangular.ts",
"./pangular-server": "./src/pangular-server.ts"
},
"peerDependencies": {
"@pangular-inspector/devtools": "^1.0.0"
},
"peerDependenciesMeta": {
"@pangular-inspector/devtools": {
"optional": true
}
}
}
```

The example points `exports` at TypeScript sources because it lives in this workspace. A published library points them at its built JavaScript and type declarations.

<ngmd-callout type="info" title="One plugin registry per page">
The registry lives on <code>globalThis</code>, and every copy of the <code>/plugin</code> entry point shares it. If your build bundles its own copy of the entry point, the overlay still finds your plugin.
</ngmd-callout>

## Write the page entry

<ngmd-workflow>
<ngmd-step title="Describe the view">
Turn your library's state into a <code>PluginView</code>: a summary, badges, sections and the actions the panel shows as buttons.
</ngmd-step>
<ngmd-step title="Define the plugin">
Give it an id, a version, a <code>collect</code> function and the page actions. If your state changes outside Angular, push a view from <code>setup</code> on each change.
</ngmd-step>
<ngmd-step title="Export a register helper">
Wrap <code>registerPangularPlugin()</code>, so apps don't build the plugin themselves.
</ngmd-step>
</ngmd-workflow>

The flag store calls its listeners on each change, which Angular does not see. The plugin subscribes in `setup` and returns the unsubscribe function as its cleanup:

```ts
// examples/pangular-plugin-example/src/pangular.ts
import {registerPangularPlugin, type PangularPagePlugin} from '@pangular-inspector/devtools/plugin';
import {FLAGS_PLUGIN_ID, FLAGS_PLUGIN_VERSION} from './ids.ts';
import type {FlagStore} from './index.ts';

// flagsView(store) builds the PluginView; it is defined just above this in the same file.
export function flagsPangularPlugin(store: FlagStore): PangularPagePlugin {
return {
id: FLAGS_PLUGIN_ID,
version: FLAGS_PLUGIN_VERSION,
title: 'Feature flags',
description: 'Flags from the example feature flag store, with their defaults and overrides.',
setup: (ctx) => store.subscribe(() => ctx.push(flagsView(store))),
Comment thread
erkamyaman marked this conversation as resolved.
Resolved
collect: () => flagsView(store),
actions: {
set: (args) => {
const {name, value} = (args ?? {}) as {name?: unknown; value?: unknown};
if (typeof name !== 'string' || typeof value !== 'boolean') {
throw new Error('Pass { name: string, value: boolean }.');
}
if (!store.set(name, value)) throw new Error(`There is no flag ${name}.`);
return {name, value};
},
reset: () => ({reset: store.reset()}),
},
};
}

export function registerFlagsPangularPlugin(store: FlagStore): () => void {
return registerPangularPlugin(flagsPangularPlugin(store));
}
```

`flagsView()`, in the same file, returns a stats section and a table of flags. Its full source is in [`examples/pangular-plugin-example/src/pangular.ts`](https://github.com/pangular-inspector/devtools/blob/main/examples/pangular-plugin-example/src/pangular.ts). It 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.

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.

## Write the server entry

The server plugin adds agent tools over what the page reports. A tool that runs a page action declares `safety: 'action'`, so `agent.readOnly` and the action switches drop it:

```ts
// examples/pangular-plugin-example/src/pangular-server.ts
import {definePangularServerPlugin} from '@pangular-inspector/devtools/plugin';
import {FLAGS_PLUGIN_ID, FLAGS_PLUGIN_VERSION} from './ids.ts';

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

export const flagsServerPlugin = definePangularServerPlugin({
id: FLAGS_PLUGIN_ID,
version: FLAGS_PLUGIN_VERSION,
title: 'Feature flags',
tools: [
{
name: 'flags',
description: 'Every flag in the feature flag store on the running page.',
inputSchema: {type: 'object', properties: {page: PAGE}},
handler: (args, ctx) => {
const page = ctx.page(pageArg(args));
if (!page?.view) return 'No page runs the feature flag store. Open the app in a browser.';
return ctx.markdown(page.view);
},
},
{
name: 'set',
safety: 'action',
description: 'Turn one flag on or off on the running page until it reloads.',
inputSchema: {
type: 'object',
properties: {name: {type: 'string'}, value: {type: 'boolean'}, page: PAGE},
required: ['name', 'value'],
},
Comment thread
erkamyaman marked this conversation as resolved.
Resolved
handler: async (args, ctx) => {
const result = await ctx.runPageAction(
'set',
{name: args['name'], value: args['value']},
{page: pageArg(args)},
);
if (!result.ok) return result.error ?? 'The action failed.';
return `Turned \`${String(args['name'])}\` ${args['value'] ? 'on' : 'off'} on page \`${result.pageId}\`.`;
},
},
],
});
```

The tools register as `pangular:plugin:feature-flags:flags` and `pangular:plugin:feature-flags:set`. See [Add agent tools](./write-a-plugin.md#add-agent-tools) for the naming and length rules.

## Use it in an app

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:

```bash group="install" name="pnpm" image="https://cdn.simpleicons.org/pnpm/F69220" active
pnpm add -D @pangular-inspector/devtools
```

```bash group="install" name="npm" image="https://cdn.simpleicons.org/npm/CB3837"
npm install -D @pangular-inspector/devtools
```

```bash group="install" name="yarn" image="https://cdn.simpleicons.org/yarn/2C8EBB"
yarn add -D @pangular-inspector/devtools
```

```bash group="install" name="bun" image="https://bun.sh/logo.svg"
bun add -D @pangular-inspector/devtools
```

Then tell the apps that use your library to make two changes.

<ngmd-workflow>
<ngmd-step title="Register the page plugin in development">
Load the <code>./pangular</code> entry point with a dynamic <code>import()</code> in the browser, in development builds only.
</ngmd-step>
<ngmd-step title="Pass the server plugin to the devtools server">
Add it to <code>serverPlugins</code> of the Vite plugin or of <code>initPangularHub()</code>.
</ngmd-step>
</ngmd-workflow>

The Analog demo keeps its flags in a `FeatureFlags` service and registers the tab from an app initializer. The dynamic import keeps the page entry out of the main bundle:

```ts
// From examples/analog/src/app/shared/feature-flags.ts
export function provideFeatureFlagsPangularPlugin(): EnvironmentProviders {
return provideAppInitializer(() => {
if (typeof ngDevMode !== 'undefined' && !ngDevMode) return;
if (!isPlatformBrowser(inject(PLATFORM_ID))) return;
const flags = inject(FeatureFlags);
Comment thread
erkamyaman marked this conversation as resolved.
Resolved
const destroyRef = inject(DestroyRef);
void import('pangular-plugin-example/pangular').then(({registerFlagsPangularPlugin}) => {
if (destroyRef.destroyed) return;
destroyRef.onDestroy(registerFlagsPangularPlugin(flags.store));
});
});
}
```

The complete file, with its imports and the `FeatureFlags` service, is [`examples/analog/src/app/shared/feature-flags.ts`](https://github.com/pangular-inspector/devtools/blob/main/examples/analog/src/app/shared/feature-flags.ts). It needs Angular 22 or later, since it uses `@Service()`, `DestroyRef.destroyed` and `provideAppInitializer()`. Add `provideFeatureFlagsPangularPlugin()` to the app's providers. Then pass the server plugin to the Vite plugin:

```ts {4,8}
// examples/analog/vite.config.ts
import analog from '@analogjs/platform';
import pangular from '@pangular-inspector/devtools/vite';
import {flagsServerPlugin} from 'pangular-plugin-example/pangular-server';
import {defineConfig} from 'vite';

export default defineConfig(() => ({
plugins: [analog(), pangular({serverPlugins: [flagsServerPlugin]})],
}));
```

An Express app passes the same array to `initPangularHub({serverPlugins})`, as [Add agent tools](./write-a-plugin.md#add-agent-tools) shows. Either way, the app must load the [overlay](../getting-started/overlay.md), or no plugin view appears in the panel.

Run `pnpm analog:dev` and open the panel. The **Plugins** tab lists **Feature flags**. Ask an agent to turn `promo-banner` on, and the banner appears on the home page.

## Test the plugin

Test the plugin the way the repository tests the example: `packages/devtools/src/__tests__/plugin-example.test.ts` registers the page plugin, runs it with the overlay's plugins collector, boots a devframe with the server plugin, and wires the two together. An agent tool call then runs the page action and returns its answer, with no browser.

For a library outside this repository, test `flagsView()` and the actions against your own store, and the tool handlers against a stub context that returns a page from `page()`.

## Where to next

<ngmd-pill-row>
<ngmd-pill href="/guides/write-a-plugin" title="Write a plugin"></ngmd-pill>
<ngmd-pill href="/getting-started/configuration" title="Configuration"></ngmd-pill>
<ngmd-pill href="/agents/tools" title="Agent tools"></ngmd-pill>
</ngmd-pill-row>
2 changes: 1 addition & 1 deletion apps/docs/src/content/guides/write-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ A plugin has up to two parts:
</ngmd-card>
</ngmd-card-grid>

The demo app ships an example plugin for its `TravelStore`: `src/app/devtools/travel-plugin.ts` for the page and `src/app/devtools/travel-plugin.server.ts` for the server. This guide builds it step by step.
The demo app ships an example plugin for its `TravelStore`: `src/app/devtools/travel-plugin.ts` for the page and `src/app/devtools/travel-plugin.server.ts` for the server. This guide builds it step by step. To publish a plugin with a library instead, see [Ship a plugin from a library](./ship-a-plugin.md).

## Write the page plugin

Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/ngmd.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ const config: NgmdConfig = {
{label: 'Set up Angular Native', href: '/guides/angular-native'},
{label: 'Set up Capacitor', href: '/guides/capacitor'},
{label: 'Write a plugin', href: '/guides/write-a-plugin'},
{label: 'Ship a plugin from a library', href: '/guides/ship-a-plugin'},
{label: 'Inspect, fix and verify', href: '/guides/inspect-fix-verify'},
],
},
Expand Down
1 change: 1 addition & 0 deletions examples/analog/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"marked-gfm-heading-id": "^4.1.1",
"marked-highlight": "^2.2.1",
"marked-mangle": "^1.1.10",
"pangular-plugin-example": "workspace:*",
"prismjs": "^1.29.0",
"rxjs": "~7.8.0",
"tslib": "^2.3.0"
Expand Down
2 changes: 2 additions & 0 deletions examples/analog/src/app/app.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { withComponentInputBinding } from '@angular/router';
import { provideContent, withMarkdownRenderer } from '@analogjs/content';
import { provideFileRouter, requestContextInterceptor } from '@analogjs/router';
import { providePangularHttp } from '@pangular-inspector/devtools/http';
import { provideFeatureFlagsPangularPlugin } from './shared/feature-flags';

export const appConfig: ApplicationConfig = {
providers: [
Expand All @@ -14,5 +15,6 @@ export const appConfig: ApplicationConfig = {
provideClientHydration(withEventReplay()),
provideContent(withMarkdownRenderer()),
providePangularHttp(),
provideFeatureFlagsPangularPlugin(),
],
};
27 changes: 17 additions & 10 deletions examples/analog/src/app/pages/index.page.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import { NgOptimizedImage } from '@angular/common';
import { Component, input } from '@angular/core';
import { Component, inject, input } from '@angular/core';
import { RouterLink } from '@angular/router';
import type { LoadResult, RouteMeta } from '@analogjs/router';
import { injectContentFiles } from '@analogjs/content';
import { FeatureFlags } from '../shared/feature-flags';
import { ProductCard } from '../shared/product-card';
import type { load } from './index.server';

Expand All @@ -19,6 +20,9 @@ export const routeMeta: RouteMeta = {
@Component({
imports: [ProductCard, RouterLink, NgOptimizedImage],
template: `
@if (flags.enabled('promo-banner')) {
<p class="promo">Free shipping on every order this week.</p>
}
<section class="hero">
<img
class="hero-logo"
Expand All @@ -42,19 +46,22 @@ export const routeMeta: RouteMeta = {
<app-product-card [product]="product" />
}
</div>
<h2>From the blog</h2>
<ul class="list">
@for (post of posts; track post.slug) {
<li>
<a [routerLink]="['/blog', post.slug]">{{ post.attributes.title }}</a>
<span class="muted">{{ post.attributes.date }}</span>
</li>
}
</ul>
@if (flags.enabled('blog-teaser')) {
<h2>From the blog</h2>
<ul class="list">
@for (post of posts; track post.slug) {
<li>
<a [routerLink]="['/blog', post.slug]">{{ post.attributes.title }}</a>
<span class="muted">{{ post.attributes.date }}</span>
</li>
}
</ul>
}
`,
})
export default class Home {
readonly load = input.required<LoadResult<typeof load>>();
protected readonly flags = inject(FeatureFlags);
protected readonly posts = injectContentFiles<PostAttributes>((file) =>
file.filename.includes('content/blog/'),
)
Expand Down
Loading
Loading