DevTools Kit Extensions

/**
 * Add a custom tab to devtools interface
 * Provide a function to pass a factory that can be updated dynamically
 * @param tab - Tab configuration or factory function
 * @param nuxt - Nuxt instance (optional, uses current context)
 */
function addCustomTab(
  tab: ModuleCustomTab | (() => ModuleCustomTab | Promise<ModuleCustomTab>),
  nuxt?: Nuxt
): void;

/**
 * Retrigger update for custom tabs
 * Causes 'devtools:customTabs' hook to be called again
 * @param nuxt - Nuxt instance (optional)
 */
function refreshCustomTabs(nuxt?: Nuxt): Promise<void>;

import { addCustomTab, refreshCustomTabs } from "@nuxt/devtools-kit";

// Static tab configuration
addCustomTab({
  name: 'my-module',
  title: 'My Module',
  icon: 'carbon:apps',
  view: {
    type: 'iframe',
    src: '/__my-module'
  }
});

// Dynamic tab with factory function
addCustomTab(async () => {
  const config = await getModuleConfig();
  return {
    name: 'dynamic-module',
    title: config.displayName,
    icon: config.icon,
    view: {
      type: 'iframe',
      src: config.devUrl
    }
  };
});

// Refresh tabs after configuration change
refreshCustomTabs();

/**
 * Extend server RPC with custom functions for devtools communication
 * @param namespace - Unique namespace for RPC functions
 * @param functions - Object containing server-side functions
 * @param nuxt - Nuxt instance (optional)
 * @returns BirpcGroup for client-server communication
 */
function extendServerRpc<ClientFunctions = Record<string, never>, ServerFunctions = Record<string, never>>(
  namespace: string,
  functions: ServerFunctions,
  nuxt?: Nuxt
): BirpcGroup<ClientFunctions, ServerFunctions>;

import { extendServerRpc } from "@nuxt/devtools-kit";

// Define server-side functions
const serverFunctions = {
  async getModuleData() {
    return await fetchModuleData();
  },
  
  async updateConfiguration(config: ModuleConfig) {
    await saveConfiguration(config);
    return { success: true };
  },
  
  async executeCommand(command: string) {
    const result = await exec(command);
    return result;
  }
};

// Define client-side function types
interface ClientFunctions {
  onConfigurationChanged(config: ModuleConfig): void;
  onDataUpdated(data: any): void;
}

// Extend RPC with custom namespace
const rpc = extendServerRpc<ClientFunctions, typeof serverFunctions>(
  'my-module',
  serverFunctions
);

// Call client functions from server
rpc.onConfigurationChanged(newConfig);

// Client can call server functions via:
// rpc.getModuleData()
// rpc.updateConfiguration(config)

/**
 * Create a subprocess that is managed by the DevTools terminal interface
 * @param execaOptions - Command execution options
 * @param tabOptions - Terminal tab configuration
 * @param nuxt - Nuxt instance (optional)
 * @returns Controller object for managing the subprocess
 */
function startSubprocess(
  execaOptions: SubprocessOptions,
  tabOptions: TerminalState,
  nuxt?: Nuxt
): SubprocessController;

interface SubprocessController {
  /** Get the current process instance */
  getProcess: () => ExecaChildProcess<string>;
  /** Terminate the subprocess */
  terminate: () => void;
  /** Restart the subprocess */
  restart: () => void;
  /** Clear terminal output buffer */
  clear: () => void;
}

import { startSubprocess } from "@nuxt/devtools-kit";

// Start a build watcher
const buildWatcher = startSubprocess(
  {
    command: 'npm',
    args: ['run', 'build:watch'],
    cwd: process.cwd(),
    env: { NODE_ENV: 'development' }
  },
  {
    id: 'build-watcher',
    name: 'Build Watcher',
    description: 'Watches and rebuilds on file changes',
    icon: 'carbon:build-tool',
    restartable: true,
    terminatable: true
  }
);

// Start a test runner
const testRunner = startSubprocess(
  {
    command: 'vitest',
    args: ['--watch', '--reporter=verbose']
  },
  {
    id: 'test-runner',
    name: 'Test Runner',
    description: 'Continuous test execution',
    icon: 'carbon:test-tool',
    restartable: true,
    terminatable: false // Prevent accidental termination
  }
);

// Control subprocess
buildWatcher.restart();
testRunner.clear();
buildWatcher.terminate();

/**
 * Register callback for when DevTools is initialized
 * @param fn - Callback function receiving initialization info
 * @param nuxt - Nuxt instance (optional)
 */
function onDevToolsInitialized(
  fn: (info: NuxtDevtoolsInfo) => void,
  nuxt?: Nuxt
): void;

import { onDevToolsInitialized } from "@nuxt/devtools-kit";

onDevToolsInitialized((info) => {
  console.log(`DevTools v${info.version} initialized`);
  console.log(`Package path: ${info.packagePath}`);
  console.log(`Time metrics enabled: ${info.timeMetrics}`);
  
  // Setup module-specific devtools integration
  setupCustomIntegration(info);
});

// Advanced initialization with module configuration
onDevToolsInitialized((info) => {
  if (info.timeMetrics) {
    enablePerformanceTracking();
  }
  
  // Register custom hooks based on devtools capabilities
  registerCustomHooks(info.version);
});

interface ModuleCustomTab {
  /** The name of the tab, must be unique */
  name: string;
  /** Icon of the tab, support any Iconify icons, or a url to an image */
  icon?: string;
  /** Title of the tab */
  title: string;
  /** Main view of the tab */
  view: ModuleView;
  /** Category of the tab (default: 'app') */
  category?: TabCategory;
  /** Insert static vnode to the tab entry (advanced option) */
  extraTabVNode?: VNode;
  /** Require local authentication to access the tab (default: false) */
  requireAuth?: boolean;
}

interface ModuleIframeView {
  /** Iframe view */
  type: 'iframe';
  /** Url of the iframe */
  src: string;
  /** Persist the iframe instance even if the tab is not active (default: true) */
  persistent?: boolean;
}

interface ModuleLaunchView {
  /** A view for module to lazy launch some actions */
  type: 'launch';
  title?: string;
  icon?: string;
  description: string;
  /** Action buttons */
  actions: ModuleLaunchAction[];
}

interface ModuleVNodeView {
  /** Vue's VNode view */
  type: 'vnode';
  /** Send vnode to the client, they must be static and serializable */
  vnode: VNode;
}

type ModuleView = ModuleIframeView | ModuleLaunchView | ModuleVNodeView;

interface ModuleLaunchAction {
  /** Label of the action button */
  label: string;
  /** Additional HTML attributes to the action button */
  attrs?: Record<string, string>;
  /** Indicate if the action is pending, will show a loading indicator and disable the button */
  pending?: boolean;
  /** Function to handle the action, this is executed on the server side */
  handle?: () => void | Promise<void>;
  /** Treat the action as a link, will open the link in a new tab */
  src?: string;
}

type TabCategory = 'pinned' | 'app' | 'vue-devtools' | 'analyze' | 'server' | 'modules' | 'documentation' | 'advanced';

interface TerminalState {
  /** Unique identifier for terminal */
  id: string;
  /** Display name in terminal tab */
  name: string;
  /** Optional description */
  description?: string;
  /** Icon for terminal tab */
  icon?: string;
  /** Allow restart action */
  restartable?: boolean;
  /** Allow terminate action */
  terminatable?: boolean;
  /** Current terminal output buffer */
  buffer?: string;
}

interface SubprocessOptions {
  /** Command to execute */
  command: string;
  /** Command arguments */
  args?: string[];
  /** Working directory */
  cwd?: string;
  /** Environment variables */
  env?: Record<string, string>;
  /** Additional execa options */
  [key: string]: any;
}

interface NuxtDevtoolsInfo {
  /** DevTools version */
  version: string;
  /** Path to devtools package */
  packagePath: string;
  /** Whether time metrics are enabled */
  timeMetrics: boolean;
}

interface BirpcGroup<ClientFunctions, ServerFunctions> {
  /** Call server function from client */
  [K in keyof ServerFunctions]: ServerFunctions[K];
} & {
  /** Call client function from server */
  [K in keyof ClientFunctions]: ClientFunctions[K];
}

// Available hooks for devtools integration
nuxt.hook('devtools:customTabs', (tabs: ModuleCustomTab[]) => {
  // Called when custom tabs are collected
});

nuxt.hook('devtools:customTabs:refresh', () => {
  // Called when tabs need to be refreshed
});

nuxt.hook('devtools:initialized', (info: NuxtDevtoolsInfo) => {
  // Called when devtools is fully initialized
});

nuxt.hook('devtools:terminal:write', ({ id, data }: { id: string, data: string }) => {
  // Called when terminal output is written
});

nuxt.hook('devtools:terminal:exit', ({ id, code }: { id: string, code: number }) => {
  // Called when terminal process exits
});

nuxt.hook('devtools:terminal:register', (terminal: TerminalState) => {
  // Called when terminal is registered
});

nuxt.hook('devtools:terminal:remove', ({ id }: { id: string }) => {
  // Called when terminal is removed
});