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
17 changes: 17 additions & 0 deletions docs/guide/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
35 changes: 33 additions & 2 deletions packages/core/src/node/plugin-options.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { TerminalsOptions } from '@devframes/plugin-terminals'
import type { DevToolsConfig } from './config'

export type DevToolsBrandingLogo
Expand Down Expand Up @@ -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<Record<DevToolsBuiltinIntegrationId, boolean>>
}

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. */
Expand Down
51 changes: 51 additions & 0 deletions packages/core/src/node/plugins/__tests__/builtin.test.ts
Original file line number Diff line number Diff line change
@@ -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([])
})
})
66 changes: 47 additions & 19 deletions packages/core/src/node/plugins/builtin.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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. */
Expand Down Expand Up @@ -92,26 +93,49 @@ 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<DevToolsBuiltinOptions> | 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<Plugin[]> {
const plugins: (Plugin | Promise<Plugin[] | Plugin>)[] = []

// When the built-in DevTools UI is disabled, contribute nothing: the host
// 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())
}
Expand All @@ -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({
Expand Down
Loading