0
# Runtime Composables
1

2
Runtime utilities for accessing devtools functionality within Nuxt applications during development mode.
3

4
## Capabilities
5

6
### useNuxtDevTools
7

8
Vue composable that provides access to the devtools host client for runtime interaction.
9

10
```typescript { .api }
11
/**
12
 * Get Nuxt DevTools client for host app
13
 * Returns undefined if not in development mode or devtools is not enabled
14
 * @returns Reactive reference to devtools host client
15
 */
16
function useNuxtDevTools(): Ref<NuxtDevtoolsHostClient | undefined>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
// Auto-imported when devtools module is enabled
23
export default defineComponent({
24
  setup() {
25
    const devtools = useNuxtDevTools();
26
    
27
    // Check if devtools is available
28
    watchEffect(() => {
29
      if (devtools.value) {
30
        console.log('DevTools client is available');
31
        // Access RPC methods for communication
32
      } else {
33
        console.log('DevTools not available (production or disabled)');
34
      }
35
    });
36
    
37
    return {
38
      devtools
39
    };
40
  }
41
});
42

43
// In a composable
44
export function useCustomDevtoolsIntegration() {
45
  const devtools = useNuxtDevTools();
46
  
47
  const sendData = (data: any) => {
48
    if (devtools.value) {
49
      // Send data to devtools interface
50
      devtools.value.rpc?.call('custom:sendData', data);
51
    }
52
  };
53
  
54
  return { sendData };
55
}
56
```
57

58
### DevTools Host Client Interface
59

60
The client interface exposed through useNuxtDevTools for runtime communication.
61

62
```typescript { .api }
63
interface NuxtDevtoolsHostClient {
64
  /** RPC communication interface */
65
  rpc?: {
66
    /** Call remote procedure on devtools */
67
    call(method: string, ...args: any[]): Promise<any>;
68
    /** Listen for events from devtools */
69
    on(event: string, handler: (...args: any[]) => void): void;
70
    /** Remove event listener */
71
    off(event: string, handler: (...args: any[]) => void): void;
72
  };
73
  
74
  /** DevTools metadata */
75
  version?: string;
76
  
77
  /** Additional client methods (implementation-specific) */
78
  [key: string]: any;
79
}
80
```
81

82
### Runtime Availability
83

84
The composable handles different runtime contexts automatically:
85

86
- **Development Mode**: Full functionality when devtools is enabled
87
- **Production Mode**: Always returns undefined
88
- **Server-Side**: Always returns undefined (client-only)
89
- **Disabled DevTools**: Returns undefined when devtools is explicitly disabled
90

91
**Implementation Details:**
92

93
```typescript
94
// The composable uses window.__NUXT_DEVTOOLS_HOST__ for client access
95
// and automatically handles reactive updates when devtools connects
96

97
// Internal implementation pattern:
98
if (!import.meta.dev) return shallowRef(); // Production
99
if (import.meta.server) return shallowRef(); // Server-side
100

101
// Client-side reactive connection to devtools host
102
const client = shallowRef<NuxtDevtoolsHostClient | undefined>();
103

104
if (window.__NUXT_DEVTOOLS_HOST__) {
105
  client.value = window.__NUXT_DEVTOOLS_HOST__;
106
} else {
107
  // Setup reactive property for when devtools connects
108
  Object.defineProperty(window, '__NUXT_DEVTOOLS_HOST__', {
109
    set(value) { client.value = value; },
110
    get() { return client.value; }
111
  });
112
}
113
```
114

115
### DevTools Kit Runtime Composables
116

117
Additional runtime utilities from the @nuxt/devtools-kit package for advanced usage.
118

119
```typescript { .api }
120
/**
121
 * Get DevTools host client directly from kit package
122
 * Equivalent to useNuxtDevTools but from devtools-kit
123
 * @returns Reactive reference to devtools host client
124
 */
125
function useDevtoolsHostClient(): Ref<NuxtDevtoolsHostClient | undefined>;
126

127
/**
128
 * Get DevTools iframe client for custom devtools interfaces
129
 * Used for creating custom devtools UI components
130
 * @returns Reactive reference to devtools iframe client
131
 */
132
function useDevtoolsClient(): Ref<NuxtDevtoolsIframeClient | undefined>;
133

134
/**
135
 * Register callback for when DevTools host client connects
136
 * @param fn - Callback function receiving the connected client
137
 * @returns Cleanup function to remove the listener
138
 */
139
function onDevtoolsHostClientConnected(
140
  fn: (client: NuxtDevtoolsHostClient) => void
141
): (() => void) | undefined;
142

143
/**
144
 * Register callback for when DevTools iframe client connects
145
 * @param fn - Callback function receiving the connected client
146
 * @returns Cleanup function to remove the listener
147
 */
148
function onDevtoolsClientConnected(
149
  fn: (client: NuxtDevtoolsIframeClient) => void
150
): (() => void) | undefined;
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { useDevtoolsHostClient, onDevtoolsHostClientConnected } from "@nuxt/devtools-kit/host-client";
157
import { useDevtoolsClient, onDevtoolsClientConnected } from "@nuxt/devtools-kit/iframe-client";
158

159
// Using host client composable
160
export function useCustomDevtoolsIntegration() {
161
  const hostClient = useDevtoolsHostClient();
162
  
163
  const sendMetrics = (data: any) => {
164
    if (hostClient.value) {
165
      hostClient.value.rpc?.call('custom:metrics', data);
166
    }
167
  };
168
  
169
  return { sendMetrics };
170
}
171

172
// Using connection hooks
173
onDevtoolsHostClientConnected((client) => {
174
  console.log('Host client connected:', client);
175
  
176
  // Setup custom RPC handlers
177
  client.rpc?.on('custom:request', (data) => {
178
    console.log('Received custom request:', data);
179
  });
180
});
181

182
// Using iframe client for custom devtools UI
183
onDevtoolsClientConnected((client) => {
184
  console.log('Iframe client connected:', client);
185
  
186
  // Access host through iframe client
187
  if (client.host) {
188
    client.host.hooks.hook('host:update:reactivity', () => {
189
      // Handle reactivity updates
190
    });
191
  }
192
});
193
```
194

195
### DevTools Client Interfaces
196

197
```typescript { .api }
198
interface NuxtDevtoolsIframeClient {
199
  /** Host client interface when available */
200
  host?: NuxtDevtoolsHostClient;
201
  /** Additional iframe-specific methods */
202
  [key: string]: any;
203
}
204
```