From 95b1a89cb34ca8b2da42f4c777c2e27c162fa8a7 Mon Sep 17 00:00:00 2001 From: arlo Date: Tue, 10 Nov 2026 12:44:25 +0800 Subject: [PATCH] feat(core): configure built-in features --- docs/guide/index.md | 17 +++++ packages/core/src/node/plugin-options.ts | 35 +++++++++- .../node/plugins/__tests__/builtin.test.ts | 51 ++++++++++++++ packages/core/src/node/plugins/builtin.ts | 66 +++++++++++++------ 4 files changed, 148 insertions(+), 21 deletions(-) create mode 100644 packages/core/src/node/plugins/__tests__/builtin.test.ts diff --git a/docs/guide/index.md b/docs/guide/index.md index a45503cee..864146aff 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -99,6 +99,23 @@ export default defineConfig({ }) ``` +### Configure built-in features + +`builtinDevTools` controls the built-in panels and integrations. `true` (the default) mounts all of them and `false` mounts none. Pass an object to toggle the Terminals, Messages, and Inspect panels and the integrations individually; entries you leave out stay enabled. `terminals` also accepts [`@devframes/plugin-terminals`](https://devfra.me) options, such as a custom `shell` or command `presets`. + +```ts [vite.config.ts] +import { defineConfig } from 'vite' + +export default defineConfig({ + devtools: { + builtinDevTools: { + terminals: false, // or { shell: '/bin/zsh' } + integrations: { oxc: false }, + }, + }, +}) +``` + #### Projects without an HTML entry For apps where Vite doesn't serve the HTML (JS-only entries, backend integration, middleware mode), load the client script that the dev server hosts at `/__devtools/embedded.js` from a browser entry instead: diff --git a/packages/core/src/node/plugin-options.ts b/packages/core/src/node/plugin-options.ts index 6ba4a72be..9af9dddc9 100644 --- a/packages/core/src/node/plugin-options.ts +++ b/packages/core/src/node/plugin-options.ts @@ -1,3 +1,4 @@ +import type { TerminalsOptions } from '@devframes/plugin-terminals' import type { DevToolsConfig } from './config' export type DevToolsBrandingLogo @@ -41,13 +42,43 @@ export interface ViteDevToolsUiOptions { dockPreferences?: DevToolsDockPreferences } +export type DevToolsBuiltinIntegrationId = 'rolldown' | 'vite' | 'vitest' | 'oxc' + +export interface DevToolsBuiltinOptions { + /** + * Terminals panel. Pass options to configure it, e.g. a custom `shell` or `presets`. + * + * @default true + */ + terminals?: boolean | TerminalsOptions + /** + * Messages panel. + * + * @default true + */ + messages?: boolean + /** + * DevTools inspector panel. + * + * @default true + */ + inspect?: boolean + /** + * Built-in integrations (Rolldown, Vite, Vitest, Oxc), including their install launchers. + * + * @default true + */ + integrations?: boolean | Partial> +} + export interface DevToolsUserOptions { /** - * Include the Vite builtin devtools UI. + * Include the Vite builtin devtools UI. Pass an object to toggle or configure + * individual built-in panels; omitted entries stay enabled. * * @default true */ - builtinDevTools?: boolean + builtinDevTools?: boolean | DevToolsBuiltinOptions /** Dock renderer modules, replacing built-ins with the same type and appending new types. */ renderers?: readonly DevToolsDockRendererRegistration[] /** Override the branding handed to the DevTools client. */ diff --git a/packages/core/src/node/plugins/__tests__/builtin.test.ts b/packages/core/src/node/plugins/__tests__/builtin.test.ts new file mode 100644 index 000000000..4468fecb7 --- /dev/null +++ b/packages/core/src/node/plugins/__tests__/builtin.test.ts @@ -0,0 +1,51 @@ +import { isPackageExists } from 'local-pkg' +import { describe, expect, it, vi } from 'vitest' +import { DevToolsBuiltin, resolveBuiltinOptions } from '../builtin' + +vi.mock('local-pkg', () => ({ + isPackageExists: vi.fn(() => false), +})) + +describe('resolveBuiltinOptions', () => { + it('enables every panel by default and for `true`', () => { + const expected = { terminals: true, messages: true, inspect: true, integrations: true } + expect(resolveBuiltinOptions()).toEqual(expected) + expect(resolveBuiltinOptions(true)).toEqual(expected) + expect(resolveBuiltinOptions({})).toEqual(expected) + }) + + it('disables everything for `false`', () => { + expect(resolveBuiltinOptions(false)).toBeUndefined() + }) + + it('keeps omitted panels enabled in the object form', () => { + expect(resolveBuiltinOptions({ terminals: false })) + .toEqual({ terminals: false, messages: true, inspect: true, integrations: true }) + }) + + it('passes terminal options through', () => { + expect(resolveBuiltinOptions({ terminals: { shell: '/bin/sh' } })?.terminals) + .toEqual({ shell: '/bin/sh' }) + }) +}) + +describe('devToolsBuiltin', () => { + it('skips disabled integrations', async () => { + vi.mocked(isPackageExists).mockClear() + await DevToolsBuiltin({ builtinDevTools: { integrations: { vitest: false, oxc: false } } }) + + expect(vi.mocked(isPackageExists).mock.calls.map(([pkg]) => pkg)) + .toEqual(['@vitejs/devtools-rolldown', '@vitejs/devtools-vite']) + }) + + it('skips every integration when disabled as a group', async () => { + vi.mocked(isPackageExists).mockClear() + await DevToolsBuiltin({ builtinDevTools: { integrations: false } }) + + expect(vi.mocked(isPackageExists)).not.toHaveBeenCalled() + }) + + it('contributes nothing when disabled', async () => { + expect(await DevToolsBuiltin({ builtinDevTools: false })).toEqual([]) + }) +}) diff --git a/packages/core/src/node/plugins/builtin.ts b/packages/core/src/node/plugins/builtin.ts index de700c33f..73f8a4a92 100644 --- a/packages/core/src/node/plugins/builtin.ts +++ b/packages/core/src/node/plugins/builtin.ts @@ -1,4 +1,5 @@ import type { Plugin } from 'vite' +import type { DevToolsBuiltinIntegrationId, DevToolsBuiltinOptions } from '../plugin-options' import process from 'node:process' import { createInspectDevframe } from '@devframes/plugin-inspect' import { createMessagesDevframe } from '@devframes/plugin-messages' @@ -13,7 +14,7 @@ import { hideDockWhenEmpty } from './auto-hide' interface BuiltinLauncherIntegration { /** Dock id, shared by the install launcher and the mounted integration. */ - id: string + id: DevToolsBuiltinIntegrationId /** Package whose presence means the integration is already installed. */ pkg: string /** Dock title. */ @@ -92,13 +93,32 @@ const BUILTIN_LAUNCHER_INTEGRATIONS: BuiltinLauncherIntegration[] = [ }, ] +/** + * Normalize `builtinDevTools` into per-feature switches. `false` disables every + * built-in (returns `undefined`); in the object form, omitted entries stay enabled. + */ +export function resolveBuiltinOptions( + options: boolean | DevToolsBuiltinOptions = true, +): Required | undefined { + if (options === false) + return + + const config = options === true ? {} : options + return { + terminals: config.terminals ?? true, + messages: config.messages ?? true, + inspect: config.inspect ?? true, + integrations: config.integrations ?? true, + } +} + /** * Set up the built-in DevTools dock entries (Terminals, Messages, Inspector) and * the built-in integration launchers (Rolldown, Vite, Vitest, Oxc). */ export async function DevToolsBuiltin(options: { cwd?: string - builtinDevTools?: boolean + builtinDevTools?: boolean | DevToolsBuiltinOptions }): Promise { const plugins: (Plugin | Promise)[] = [] @@ -106,12 +126,16 @@ export async function DevToolsBuiltin(options: { // mounts its own built-in docks (terminals / messages / inspector) and // integrations by hand. Mounting them here too would double-register each // devframe on the hub (DF8105) and its RPC functions (DF0021). - if (!options.builtinDevTools) + const builtin = resolveBuiltinOptions(options.builtinDevTools) + if (!builtin) return [] const cwd = resolve(options.cwd ?? process.cwd()) const launchers: BuiltinLauncherIntegration[] = [] + const { integrations } = builtin for (const integration of BUILTIN_LAUNCHER_INTEGRATIONS) { + if (integrations === false || (integrations !== true && integrations[integration.id] === false)) + continue if (isPackageExists(integration.pkg, { paths: [cwd] })) { plugins.push(integration.load()) } @@ -136,27 +160,31 @@ export async function DevToolsBuiltin(options: { // An empty messages feed should hide its tab, so we attach that rule here — // the dock is filtered out of the bar (`when: 'false'`) whenever there are // no messages. - const terminalsDevframe = createTerminalsDevframe() - const messagesDevframe = createMessagesDevframe() - const inspectDevframe = createInspectDevframe({ id: DEVTOOLS_INSPECTOR_DOCK_ID }) - - plugins.push(createPluginFromDevframe(terminalsDevframe, { - dock: { category: '~builtin' }, - })) - plugins.push(createPluginFromDevframe(messagesDevframe, { - dock: { category: '~builtin' }, - setup(ctx) { - hideDockWhenEmpty(ctx, messagesDevframe.id, () => ctx.messages.entries.size === 0) - }, - })) + if (builtin.terminals) { + const terminalsOptions = builtin.terminals === true ? undefined : builtin.terminals + plugins.push(createPluginFromDevframe(createTerminalsDevframe(terminalsOptions), { + dock: { category: '~builtin' }, + })) + } + if (builtin.messages) { + const messagesDevframe = createMessagesDevframe() + plugins.push(createPluginFromDevframe(messagesDevframe, { + dock: { category: '~builtin' }, + setup(ctx) { + hideDockWhenEmpty(ctx, messagesDevframe.id, () => ctx.messages.entries.size === 0) + }, + })) + } // Meta-introspection ("DevTools for the DevTools"), provided by the // official devframe inspector plugin (replaces the former // `@vitejs/devtools-self-inspect` package). Pinned to a stable id so the // client can gate it behind the `showDevframeInspector` user setting; // hidden by default (opt in via Settings → Advanced). - plugins.push(createPluginFromDevframe(inspectDevframe, { - dock: { category: '~builtin', icon: 'ph:stethoscope-duotone' }, - })) + if (builtin.inspect) { + plugins.push(createPluginFromDevframe(createInspectDevframe({ id: DEVTOOLS_INSPECTOR_DOCK_ID }), { + dock: { category: '~builtin', icon: 'ph:stethoscope-duotone' }, + })) + } for (const integration of launchers) { plugins.push(createInstallLauncher({