Skip to content

Commit e57c0fe

Browse files
AlemTuzlakAlemTuzlak
committed
feat: add Angular support with setup, adapter, and custom plugin documentation
1 parent b56b0af commit e57c0fe

File tree

7 files changed

+492
-1
lines changed

7 files changed

+492
-1
lines changed

‎docs/config.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,13 @@
4545
{ "label": "Basic Setup", "to": "framework/vue/basic-setup" },
4646
{ "label": "Vue Adapter", "to": "framework/vue/adapter" }
4747
]
48+
},
49+
{
50+
"label": "angular",
51+
"children": [
52+
{ "label": "Basic Setup", "to": "framework/angular/basic-setup" },
53+
{ "label": "Angular Adapter", "to": "framework/angular/adapter" }
54+
]
4855
}
4956
]
5057
},
@@ -89,6 +96,12 @@
8996
"children": [
9097
{ "label": "Custom Plugins", "to": "framework/vue/guides/custom-plugins" }
9198
]
99+
},
100+
{
101+
"label": "angular",
102+
"children": [
103+
{ "label": "Custom Plugins", "to": "framework/angular/guides/custom-plugins" }
104+
]
92105
}
93106
]
94107
},
@@ -121,6 +134,12 @@
121134
"children": [
122135
{ "label": "Vue Reference", "to": "framework/vue/reference/index" }
123136
]
137+
},
138+
{
139+
"label": "angular",
140+
"children": [
141+
{ "label": "Angular Reference", "to": "framework/angular/reference/index" }
142+
]
124143
}
125144
]
126145
},

‎docs/devtools-utils.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,9 @@ import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
3737

3838
// Vue
3939
import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
40+
41+
// Angular
42+
import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/angular'
4043
```
4144

4245
## React
@@ -252,6 +255,49 @@ const [MyPanel, NoOpPanel] = createVuePanel(MyDevtoolsCore)
252255

253256
The panel component accepts `theme` and `devtoolsProps` as props. It mounts the core instance into a `div` element on `onMounted` and calls `unmount()` on `onUnmounted`.
254257

258+
## Angular
259+
260+
### createAngularPlugin
261+
262+
The Angular factory takes a `name` string and an Angular component class as separate arguments, similar to the Vue API.
263+
264+
**Signature:**
265+
266+
```ts
267+
function createAngularPlugin(
268+
name: string,
269+
component: Type<any>,
270+
): readonly [Plugin, NoOpPlugin]
271+
```
272+
273+
**Usage:**
274+
275+
```ts
276+
import { createAngularPlugin } from '@tanstack/devtools-utils/angular'
277+
import { MyStorePanelComponent } from './my-store-panel.component'
278+
279+
const [MyPlugin, NoOpPlugin] = createAngularPlugin('My Store', MyStorePanelComponent)
280+
```
281+
282+
The returned functions:
283+
284+
- **`Plugin(inputs?)`** -- returns `{ name, component, inputs }` where `component` is your Angular component class.
285+
- **`NoOpPlugin(inputs?)`** -- returns `{ name, component: NoOpComponent, inputs }` where the component is an empty standalone component (renders nothing visible).
286+
287+
Both accept an optional `inputs` object that gets forwarded to the component via `setInput()`.
288+
289+
### createAngularPanel
290+
291+
For class-based devtools cores, Angular provides `createAngularPanel`. It creates a standalone Angular component that handles mounting and unmounting the core class:
292+
293+
```ts
294+
import { createAngularPanel } from '@tanstack/devtools-utils/angular'
295+
296+
const [MyPanel, NoOpPanel] = createAngularPanel(MyDevtoolsCore)
297+
```
298+
299+
The panel component accepts `theme` and `devtoolsProps` as signal inputs. It mounts the core instance into a `div` element using `afterNextRender` and calls `unmount()` via `DestroyRef.onDestroy`.
300+
255301
## When to Use Factories vs Manual Plugin Objects
256302

257303
**Use the factories** when you are building a reusable library plugin that will be published as a package. The factories ensure:

‎docs/framework/angular/adapter.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: TanStack Devtools Angular Adapter
3+
id: adapter
4+
---
5+
6+
The Angular adapter wraps `TanStackDevtoolsCore` in an Angular standalone component, using Angular's `createComponent` and `ApplicationRef.attachView` to dynamically render plugins into the correct DOM containers managed by the devtools shell.
7+
8+
## Installation
9+
10+
```sh
11+
npm install @tanstack/angular-devtools
12+
```
13+
14+
## Component Inputs
15+
16+
The `TanStackDevtoolsComponent` (selector: `tanstack-devtools`) accepts the following signal-based inputs, defined by the `TanStackDevtoolsAngularInit` interface:
17+
18+
| Input | Type | Description |
19+
| --- | --- | --- |
20+
| `plugins` | `TanStackDevtoolsAngularPlugin[]` | Array of plugins to render inside the devtools panel. |
21+
| `config` | `Partial<TanStackDevtoolsConfig>` | Configuration for the devtools shell. Sets the initial state on first load; afterwards settings are persisted in local storage. |
22+
| `eventBusConfig` | `ClientEventBusConfig` | Configuration for the TanStack Devtools client event bus. |
23+
24+
## Plugin Type
25+
26+
Each plugin in the `plugins` array must conform to the `TanStackDevtoolsAngularPlugin` type:
27+
28+
```ts
29+
type TanStackDevtoolsAngularPlugin = {
30+
id?: string
31+
component: Type<any>
32+
name: string | Type<any>
33+
inputs?: Record<string, any>
34+
defaultOpen?: boolean
35+
}
36+
```
37+
38+
| Field | Type | Description |
39+
| --- | --- | --- |
40+
| `id` | `string` (optional) | Unique identifier for the plugin. |
41+
| `component` | `Type<any>` | The Angular component class to render as the plugin panel content. |
42+
| `name` | `string \| Type<any>` | Display name for the tab title. Can be a plain string or an Angular component class for custom rendering. |
43+
| `inputs` | `Record<string, any>` (optional) | Additional inputs passed to the plugin component via `setInput()`. |
44+
| `defaultOpen` | `boolean` (optional) | Whether this plugin tab should be open by default. |
45+
46+
## Key Differences from Other Frameworks
47+
48+
The Angular adapter uses `component` (an Angular component class reference) instead of `render` (a JSX element) in plugin definitions. Inputs are provided through the `inputs` field and bound to the component with `setInput()`, rather than being embedded directly in a JSX expression or passed via `v-bind`.
49+
50+
```typescript
51+
import { Component } from '@angular/core'
52+
import { TanStackDevtoolsComponent } from '@tanstack/angular-devtools'
53+
import { AngularQueryDevtoolsPanel } from '@tanstack/angular-query-devtools'
54+
55+
@Component({
56+
selector: 'app-root',
57+
standalone: true,
58+
imports: [TanStackDevtoolsComponent],
59+
template: `
60+
<tanstack-devtools [plugins]="plugins" />
61+
`,
62+
})
63+
export class AppComponent {
64+
plugins = [
65+
{
66+
name: 'Angular Query',
67+
component: AngularQueryDevtoolsPanel,
68+
inputs: { style: 'height: 100%' },
69+
},
70+
]
71+
}
72+
```
73+
74+
## Exports
75+
76+
The `@tanstack/angular-devtools` package exports:
77+
78+
- **`TanStackDevtoolsComponent`** -- The main Angular standalone component that renders the devtools panel.
79+
- **`TanStackDevtoolsAngularPlugin`** (type) -- The type for plugin definitions.
80+
- **`TanStackDevtoolsAngularInit`** (type) -- The inputs interface for the `TanStackDevtoolsComponent`.
81+
82+
The package depends on `@tanstack/devtools` (the core package), which provides `TanStackDevtoolsCore`, `TanStackDevtoolsConfig`, `ClientEventBusConfig`, and other core utilities.

‎docs/framework/angular/basic-setup.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Basic setup
3+
id: basic-setup
4+
---
5+
6+
TanStack Devtools provides you with an easy-to-use and modular client that allows you to compose multiple devtools into one easy-to-use panel.
7+
8+
## Setup
9+
10+
Install the [TanStack Devtools](https://www.npmjs.com/package/@tanstack/angular-devtools) library. This will install the devtools core as well as provide you with the Angular-specific adapter.
11+
12+
```bash
13+
npm i @tanstack/angular-devtools
14+
```
15+
16+
Next, in the root of your application, import the `TanStackDevtoolsComponent` from `@tanstack/angular-devtools` and add it to your template.
17+
18+
```typescript
19+
import { Component } from '@angular/core'
20+
import { TanStackDevtoolsComponent } from '@tanstack/angular-devtools'
21+
22+
@Component({
23+
selector: 'app-root',
24+
standalone: true,
25+
imports: [TanStackDevtoolsComponent],
26+
template: `
27+
<app-content />
28+
<tanstack-devtools />
29+
`,
30+
})
31+
export class AppComponent {}
32+
```
33+
34+
Import the desired devtools and provide them to the `TanStackDevtoolsComponent` via the `[plugins]` input along with a label for the menu.
35+
36+
```typescript
37+
import { Component } from '@angular/core'
38+
import { TanStackDevtoolsComponent } from '@tanstack/angular-devtools'
39+
import type { TanStackDevtoolsAngularPlugin } from '@tanstack/angular-devtools'
40+
import { AngularQueryDevtoolsPanel } from '@tanstack/angular-query-devtools'
41+
42+
@Component({
43+
selector: 'app-root',
44+
standalone: true,
45+
imports: [TanStackDevtoolsComponent],
46+
template: `
47+
<app-content />
48+
<tanstack-devtools [plugins]="plugins" />
49+
`,
50+
})
51+
export class AppComponent {
52+
plugins: Array<TanStackDevtoolsAngularPlugin> = [
53+
{
54+
name: 'Angular Query',
55+
component: AngularQueryDevtoolsPanel,
56+
},
57+
]
58+
}
59+
```
60+
61+
> Note: The Angular adapter uses `component` (an Angular component class) instead of `render` (a JSX element) in plugin definitions. Additional inputs can be provided via the `inputs` field and are bound to the component with `setInput()`.
62+
63+
Finally, add any additional configuration you desire to the `TanStackDevtoolsComponent`. More information can be found under the [TanStack Devtools Configuration](../../configuration) section.

0 commit comments

Comments
 (0)