@mintlify/previewing 4.0.1461 → 4.0.1463

package/dist/__tests__/packages-flag.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/packages-flag.test.js

@@ -0,0 +1,146 @@
+import { prebuild } from '@mintlify/prebuild';
+import { mockProcessExit } from 'vitest-mock-process';
+import { configurePreviewPath } from '../constants.js';
+import { dev, isNativePackagesEnabled } from '../index.js';
+import listener from '../local-preview/listener/index.js';
+import { packageRoute, setPackagesRebuiltListener, startPackagesDev, } from '../local-preview/packages/index.js';
+const captured = vi.hoisted(() => ({ app: undefined }));
+vi.mock('http', async (importOriginal) => {
+    const actual = await importOriginal();
+    const createServer = (app) => {
+        captured.app = app;
+        return { listen: vi.fn() };
+    };
+    return { ...actual, default: { ...actual, createServer }, createServer };
+});
+vi.mock('socket.io', () => ({
+    Server: vi.fn(() => ({ emit: vi.fn(), on: vi.fn() })),
+}));
+vi.mock('fs-extra', () => {
+    const mocks = {
+        ensureDir: vi.fn().mockResolvedValue(undefined),
+        pathExists: vi.fn().mockResolvedValue(true),
+        readFileSync: vi.fn().mockReturnValue('0.0.100'),
+        emptyDirSync: vi.fn(),
+        outputFileSync: vi.fn(),
+    };
+    return { ...mocks, default: mocks };
+});
+vi.mock('@mintlify/prebuild', () => ({
+    prebuild: vi.fn().mockResolvedValue(undefined),
+    getFileListSync: vi.fn().mockReturnValue([]),
+}));
+vi.mock('is-online', () => ({ default: vi.fn().mockResolvedValue(true) }));
+vi.mock('../local-preview/update.js', () => ({
+    silentUpdateClient: vi.fn().mockResolvedValue({ needsUpdate: false, error: undefined }),
+}));
+vi.mock('../local-preview/preview-lock.js', () => ({
+    acquirePreviewLock: vi.fn().mockReturnValue(vi.fn()),
+}));
+vi.mock('../util.js', () => ({
+    maybeFixMissingWindowsEnvVar: vi.fn(),
+    seedPreviewFromShared: vi.fn(),
+}));
+vi.mock('../local-preview/run.js', () => ({ run: vi.fn().mockResolvedValue(undefined) }));
+vi.mock('../local-preview/setupNext.js', () => ({
+    setupNext: vi.fn(async () => (_req, res) => {
+        res.end('next');
+    }),
+}));
+vi.mock('../local-preview/listener/index.js', () => ({
+    default: vi.fn(),
+    initializeImportCache: vi.fn(),
+    initializeFrontmatterHashCache: vi.fn(),
+    initializeDocsConfigHashCache: vi.fn(),
+}));
+vi.mock('../local-preview/listener/referencedFiles.js', () => ({
+    refreshTrackedReferencedFiles: vi.fn(),
+}));
+vi.mock('../local-preview/on-demand-page.js', () => ({
+    ensurePageCompiled: vi.fn().mockResolvedValue(undefined),
+    getFailedCompileEvents: vi.fn().mockReturnValue([]),
+    markOnDemandPagesReady: vi.fn(),
+    setCompileListener: vi.fn(),
+}));
+vi.mock('../local-preview/packages/index.js', () => ({
+    startPackagesDev: vi.fn().mockResolvedValue(undefined),
+    setPackagesRebuiltListener: vi.fn(),
+    packageRoute: {
+        prefix: '/_mintlify/pkg',
+        handler: vi.fn((_req, res) => res.end('pkg')),
+    },
+}));
+const originalChdir = process.chdir;
+const processExitMock = mockProcessExit();
+const argv = { _: [], $0: '', packageName: 'mint', cliVersion: '1.0.0' };
+const setFlag = (value) => vi.stubEnv('MINTLIFY_NATIVE_NPM_PACKAGES', value);
+const startRun = async () => {
+    const { run } = await vi.importActual('../local-preview/run.js');
+    await run({ ...argv, needsUpdate: false });
+};
+const get = async (path) => {
+    const { createServer } = await vi.importActual('http');
+    const server = createServer(captured.app);
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    try {
+        const { port } = server.address();
+        return await (await fetch(`http://127.0.0.1:${port}${path}`)).text();
+    }
+    finally {
+        await new Promise((resolve) => server.close(resolve));
+    }
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    process.chdir = vi.fn();
+    captured.app = undefined;
+});
+afterEach(() => {
+    process.chdir = originalChdir;
+    vi.unstubAllEnvs();
+});
+describe('isNativePackagesEnabled', () => {
+    it('is on only when MINTLIFY_NATIVE_NPM_PACKAGES is 1', () => {
+        setFlag(undefined);
+        expect(isNativePackagesEnabled()).toBe(false);
+        setFlag('true');
+        expect(isNativePackagesEnabled()).toBe(false);
+        setFlag('0');
+        expect(isNativePackagesEnabled()).toBe(false);
+        setFlag('1');
+        expect(isNativePackagesEnabled()).toBe(true);
+    });
+});
+describe('mint dev with native npm packages off', () => {
+    beforeEach(() => setFlag(undefined));
+    it('skips the packages runtime and tells prebuild to ignore packages', async () => {
+        await dev(argv);
+        expect(processExitMock).not.toHaveBeenCalled();
+        expect(startPackagesDev).not.toHaveBeenCalled();
+        expect(prebuild).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ nativePackages: false }));
+    });
+    it('lets /_mintlify/pkg requests fall through to the next handler', async () => {
+        configurePreviewPath(3000);
+        await startRun();
+        expect(await get('/_mintlify/pkg/x/client/a.js')).toBe('next');
+        expect(packageRoute.handler).not.toHaveBeenCalled();
+        expect(setPackagesRebuiltListener).not.toHaveBeenCalled();
+        expect(listener).toHaveBeenCalledWith(expect.any(Function), expect.objectContaining({ nativePackages: false }), expect.any(Promise));
+    });
+});
+describe('mint dev with MINTLIFY_NATIVE_NPM_PACKAGES=1', () => {
+    beforeEach(() => setFlag('1'));
+    it('starts the packages runtime and tells prebuild to read packages', async () => {
+        await dev(argv);
+        expect(processExitMock).not.toHaveBeenCalled();
+        expect(startPackagesDev).toHaveBeenCalledOnce();
+        expect(prebuild).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ nativePackages: true }));
+    });
+    it('serves /_mintlify/pkg from the package route', async () => {
+        configurePreviewPath(3000);
+        await startRun();
+        expect(await get('/_mintlify/pkg/x/client/a.js')).toBe('pkg');
+        expect(setPackagesRebuiltListener).toHaveBeenCalledWith(expect.any(Function));
+        expect(listener).toHaveBeenCalledWith(expect.any(Function), expect.objectContaining({ nativePackages: true }), expect.any(Promise));
+    });
+});

package/dist/__tests__/packages-imports.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/packages-imports.test.js

@@ -0,0 +1,68 @@
+import { findAndRemoveImports, getAST, stringifyTree } from '@mintlify/common';
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+const testPaths = vi.hoisted(() => ({ cmd: '', public: '' }));
+vi.mock('../constants.js', () => ({
+    get CMD_EXEC_PATH() {
+        return testPaths.cmd;
+    },
+    get NEXT_PUBLIC_PATH() {
+        return testPaths.public;
+    },
+}));
+vi.mock('../local-preview/listener/utils.js', () => ({
+    getCurrentVariables: vi.fn(async () => ({})),
+    handleParseError: vi.fn(),
+}));
+import { resolvePageImports } from '../local-preview/listener/resolve-page-imports.js';
+import { setPackageImportOptions } from '../local-preview/packages/state.js';
+const PAGE = `import { LineChart } from "recharts";
+import { Toggle } from "/snippets/toggle.jsx";
+import { Note } from "/snippets/note.mdx";
+
+<LineChart width={400} height={200} />
+
+<Toggle />
+
+<Note />
+`;
+const resolve = async () => {
+    const importsResponse = await findAndRemoveImports(getAST(PAGE, '/page.mdx'));
+    return stringifyTree(await resolvePageImports({ ...importsResponse, filename: 'page.mdx' }));
+};
+describe('page imports in mint dev with npm packages', () => {
+    let root;
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'packages-imports-'));
+        testPaths.cmd = join(root, 'docs');
+        testPaths.public = join(root, 'public');
+        await fse.ensureDir(testPaths.public);
+        await fse.outputFile(join(testPaths.cmd, 'snippets/toggle.jsx'), 'import { Switch } from "@acme/ui";\nexport const Toggle = () => <Switch />;\n');
+        await fse.outputFile(join(testPaths.cmd, 'snippets/note.mdx'), 'export const Note = () => <p>Hi</p>;\n');
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(async () => {
+        setPackageImportOptions(undefined);
+        vi.mocked(console.log).mockRestore();
+        await rm(root, { recursive: true, force: true });
+    });
+    it('strips package imports when packages are off', async () => {
+        const output = await resolve();
+        expect(output).not.toContain('import');
+        expect(output).toContain('export const Toggle');
+        expect(output).toContain('export const Note');
+    });
+    it('keeps package and package snippet imports when packages are on', async () => {
+        setPackageImportOptions({
+            packageNames: new Set(['recharts', '@acme/ui']),
+            packageSnippets: new Set(['/snippets/toggle.jsx']),
+        });
+        const output = await resolve();
+        expect(output).toContain('import {LineChart} from "recharts";');
+        expect(output).toContain('import {Toggle} from "/snippets/toggle.jsx";');
+        expect(output).not.toContain('export const Toggle');
+        expect(output).toContain('export const Note');
+    });
+});

package/dist/__tests__/packages-island-errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/packages-island-errors.test.js

@@ -0,0 +1,128 @@
+import { getFileCategory } from '@mintlify/common';
+import fse from 'fs-extra';
+import { join } from 'path';
+vi.mock('../constants.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    const { mkdtempSync } = await import('fs');
+    const { tmpdir } = await import('os');
+    const path = await import('path');
+    const root = mkdtempSync(path.join(tmpdir(), 'packages-island-errors-'));
+    return {
+        ...actual,
+        CMD_EXEC_PATH: path.join(root, 'docs'),
+        PREVIEW_PATH: path.join(root, 'preview'),
+        NEXT_PROPS_PATH: path.join(root, 'props'),
+    };
+});
+vi.mock('../local-preview/listener/regenerateAllSnippets.js', () => ({
+    regenerateAllSnippets: vi.fn().mockResolvedValue([]),
+}));
+vi.mock('@mintlify/package-builder', async (importOriginal) => {
+    const actual = await importOriginal();
+    const build = async () => ({
+        ok: true,
+        manifest: {
+            version: 1,
+            builderVersion: 'test',
+            buildId: 'b',
+            depsHash: 'd',
+            islandsHash: 'i',
+            react: { version: '18.3.1', domVersion: '18.3.1' },
+            packages: {},
+            css: [],
+            islands: {},
+            files: [],
+            diagnostics: [],
+        },
+        localFiles: [],
+        missingLocalFiles: [],
+        stats: {},
+    });
+    return { ...actual, build };
+});
+import { CMD_EXEC_PATH } from '../constants.js';
+import { notifyPackageInputChange, startPackagesDev } from '../local-preview/packages/index.js';
+import { clearErrorLogs, getCurrentErrorLogs, setLoggingCallbacks } from '../logging-state.js';
+const BROKEN = 'import { LineChart } from "recharts";\n\n<LineChart onClick={() => {}} />\n';
+const FIXED = 'import { LineChart } from "recharts";\n\n<LineChart width={400} />\n';
+const errorMessages = () => getCurrentErrorLogs().map((log) => log.props.message);
+const islandErrorCount = () => errorMessages().filter((message) => /^npm packages: bad\.mdx:3 /.test(message)).length;
+const packageErrors = () => errorMessages().filter((message) => message.startsWith('npm packages:'));
+const save = async (filename, content) => {
+    clearErrorLogs();
+    if (content !== undefined)
+        await fse.outputFile(join(CMD_EXEC_PATH, filename), content);
+    await notifyPackageInputChange(filename, getFileCategory(filename));
+};
+describe('npm package island errors in the mint dev log', () => {
+    beforeAll(() => {
+        setLoggingCallbacks(() => { }, () => { }, () => { });
+    });
+    beforeEach(async () => {
+        await fse.emptyDir(CMD_EXEC_PATH);
+        await fse.outputJson(join(CMD_EXEC_PATH, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputJson(join(CMD_EXEC_PATH, 'package.json'), {
+            dependencies: { recharts: '2.15.4' },
+        });
+        await fse.outputFile(join(CMD_EXEC_PATH, 'bad.mdx'), BROKEN);
+        await fse.outputFile(join(CMD_EXEC_PATH, 'other.mdx'), '# Other\n');
+        await fse.outputFile(join(CMD_EXEC_PATH, 'styles.css'), 'a{}');
+        clearErrorLogs();
+        await startPackagesDev();
+        expect(islandErrorCount()).toBe(1);
+    });
+    afterEach(async () => {
+        await fse.remove(join(CMD_EXEC_PATH, 'docs.json'));
+        await startPackagesDev();
+        clearErrorLogs();
+    });
+    it('keeps them after another page is saved, without repeating them', async () => {
+        await save('other.mdx', '# Other edited\n');
+        expect(islandErrorCount()).toBe(1);
+        await notifyPackageInputChange('other.mdx', 'page');
+        expect(islandErrorCount()).toBe(1);
+        await save('other.mdx', '# Other edited again\n');
+        expect(islandErrorCount()).toBe(1);
+    });
+    it('keeps them after a file that is not a page is saved', async () => {
+        await save('styles.css', 'b{}');
+        expect(islandErrorCount()).toBe(1);
+    });
+    it('keeps them next to the config error while docs.json does not parse', async () => {
+        await save('docs.json', '{ "name": "Docs", "packages": {');
+        expect(errorMessages()).toContainEqual(expect.stringMatching(/^npm packages: docs\.json could not be loaded/));
+        expect(islandErrorCount()).toBe(1);
+    });
+    it('drops them once the island is fixed and shows them again when it breaks the same way', async () => {
+        await save('bad.mdx', FIXED);
+        expect(errorMessages()).toEqual([]);
+        await save('bad.mdx', BROKEN);
+        expect(islandErrorCount()).toBe(1);
+    });
+    it('drops them when the island is fixed while another page saves at the same time', async () => {
+        clearErrorLogs();
+        await fse.outputFile(join(CMD_EXEC_PATH, 'bad.mdx'), FIXED);
+        await fse.outputFile(join(CMD_EXEC_PATH, 'other.mdx'), '# Other edited\n');
+        await Promise.all([
+            notifyPackageInputChange('other.mdx', 'page'),
+            notifyPackageInputChange('bad.mdx', 'page'),
+        ]);
+        expect(errorMessages()).toEqual([]);
+    });
+    it('drops them when the island is fixed while a stylesheet saves at the same time', async () => {
+        clearErrorLogs();
+        await fse.outputFile(join(CMD_EXEC_PATH, 'bad.mdx'), FIXED);
+        await Promise.all([
+            notifyPackageInputChange('bad.mdx', 'page'),
+            notifyPackageInputChange('styles.css', getFileCategory('styles.css')),
+        ]);
+        expect(errorMessages()).toEqual([]);
+    });
+    it('replaces them when a broken page is deleted', async () => {
+        await save('worse.mdx', BROKEN);
+        expect(packageErrors()).toHaveLength(2);
+        await fse.remove(join(CMD_EXEC_PATH, 'bad.mdx'));
+        await notifyPackageInputChange('bad.mdx', 'page');
+        expect(packageErrors()).toEqual([expect.stringMatching(/^npm packages: worse\.mdx:3 /)]);
+    });
+});

package/dist/__tests__/packages-serve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/packages-serve.test.js

@@ -0,0 +1,73 @@
+import express from 'express';
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { createServer } from 'http';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { createPackageRoute, EMPTY_ISLAND_MODULE, PACKAGE_ROUTE_PREFIX, } from '../local-preview/packages/serve.js';
+const BUILD = 'a'.repeat(32);
+describe('package route', () => {
+    let root;
+    let server;
+    let base;
+    let state;
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'packages-serve-'));
+        const buildsDir = join(root, '.mintlify', 'packages');
+        await fse.outputFile(join(buildsDir, BUILD, 'client/islands/i0123456789abcdef.js'), 'export {}');
+        await fse.outputFile(join(buildsDir, BUILD, 'client/chunk-AB12.js'), 'export const a = 1;');
+        await fse.outputFile(join(buildsDir, BUILD, 'manifest.json'), '{"islands":{}}');
+        await fse.outputFile(join(buildsDir, BUILD, 'server/islands/x.js'), 'secret');
+        await fse.outputFile(join(root, 'outside.js'), 'outside');
+        state = { enabled: true, buildsDir };
+        const app = express();
+        app.use(PACKAGE_ROUTE_PREFIX, createPackageRoute(() => state));
+        app.use((_req, res) => {
+            res.status(418).send('next');
+        });
+        server = createServer(app);
+        await new Promise((resolve) => server.listen(0, resolve));
+        base = `http://127.0.0.1:${server.address().port}${PACKAGE_ROUTE_PREFIX}`;
+    });
+    afterEach(async () => {
+        await new Promise((resolve) => server.close(resolve));
+        await rm(root, { recursive: true, force: true });
+    });
+    it('serves client files from a build under a dot folder', async () => {
+        const res = await fetch(`${base}/${BUILD}/client/islands/i0123456789abcdef.js`);
+        expect(res.status).toBe(200);
+        expect(res.headers.get('content-type')).toMatch(/javascript/);
+        expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+        expect(res.headers.get('cache-control')).toBe('no-cache');
+        expect(await res.text()).toBe('export {}');
+        expect((await fetch(`${base}/${BUILD}/client/chunk-AB12.js`)).status).toBe(200);
+    });
+    it('never serves the manifest, server bundles or paths outside client', async () => {
+        for (const path of [
+            `${BUILD}/manifest.json`,
+            `${BUILD}/server/islands/x.js`,
+            `${BUILD}/client/../manifest.json`,
+            `${BUILD}/client/%2e%2e/manifest.json`,
+            `${BUILD}/client/..%2f..%2f..%2f..%2foutside.js`,
+            `..%2f..%2foutside.js`,
+        ]) {
+            const res = await fetch(`${base}/${path}`);
+            expect(res.status, path).toBe(404);
+            expect(await res.text(), path).not.toMatch(/secret|outside|islands/);
+        }
+    });
+    it('answers a missing island entry with a module that renders nothing', async () => {
+        const res = await fetch(`${base}/pending/client/islands/i0000000000000000.js`);
+        expect(res.status).toBe(200);
+        expect(res.headers.get('content-type')).toMatch(/javascript/);
+        expect(res.headers.get('cache-control')).toBe('no-store');
+        expect(await res.text()).toBe(EMPTY_ISLAND_MODULE);
+        const mod = await import(`data:text/javascript,${encodeURIComponent(EMPTY_ISLAND_MODULE)}`);
+        expect(mod).toMatchObject({ hydrate: expect.any(Function) });
+    });
+    it('falls through to Next when packages are off', async () => {
+        state = { ...state, enabled: false };
+        const res = await fetch(`${base}/${BUILD}/client/islands/i0123456789abcdef.js`);
+        expect(res.status).toBe(418);
+    });
+});

package/dist/__tests__/packages-setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/packages-setup.test.js

@@ -0,0 +1,160 @@
+import { getMdx } from '@mintlify/common/server-mdx';
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { collectPackageIslands } from '../packages/collect.js';
+import { DocsJsonError, InvalidPackagesError, readPackagesSetup } from '../packages/setup.js';
+const PAGE = 'import { Button } from "@acme/ui";\n\n<Button label="{{label}}" />\n';
+describe('package setup config references', () => {
+    let docsRoot;
+    beforeEach(async () => {
+        docsRoot = await mkdtemp(join(tmpdir(), 'packages-setup-'));
+        await fse.outputJson(join(docsRoot, 'package.json'), {
+            dependencies: { '@acme/ui': '1.0.0' },
+        });
+    });
+    afterEach(async () => {
+        await rm(docsRoot, { recursive: true, force: true });
+    });
+    it('collects the same island ids that compilation uses with referenced variables', async () => {
+        const variables = { label: 'Synthetic label' };
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            packages: {},
+            variables: { $ref: './variables.json' },
+        });
+        await fse.outputJson(join(docsRoot, 'variables.json'), variables);
+        await fse.outputFile(join(docsRoot, 'page.mdx'), PAGE);
+        const setup = await readPackagesSetup(docsRoot);
+        const packageNames = setup?.packageNames ?? new Set();
+        const collected = await collectPackageIslands({
+            docsRoot,
+            packageNames,
+            variables: setup?.variables,
+        });
+        const compiled = await getMdx({
+            path: 'page',
+            content: PAGE,
+            metadata: {},
+            snippets: [],
+            subdomain: 'local',
+            codeStyling: undefined,
+            tailwindSelectors: [],
+            variables,
+            packageBuild: {
+                baseUrl: '/_mintlify/pkg/synthetic',
+                islands: Object.fromEntries(collected.islands.map(({ id }) => [id, { prefix: `mi-${id}-`, html: '<button />' }])),
+                packageNames: [...packageNames],
+                packageSnippets: [...collected.packageSnippets],
+            },
+        });
+        expect(setup?.variables).toEqual(variables);
+        expect(collected.errors).toEqual([]);
+        expect(collected.islands).toHaveLength(1);
+        expect(compiled.parseFailed).toBeUndefined();
+        expect(Object.keys(compiled.mdxExtracts.islands ?? {})).toEqual(collected.pages['page.mdx']?.ids);
+    });
+    it('reads referenced provider, css and ssr settings with sibling overrides', async () => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            packages: { $ref: './packages.json', ssr: false },
+        });
+        await fse.outputJson(join(docsRoot, 'packages.json'), {
+            provider: '/snippets\\provider.jsx',
+            css: ['@acme/ui/styles.css'],
+            ssr: true,
+        });
+        expect((await readPackagesSetup(docsRoot))?.packages).toEqual({
+            provider: '/snippets/provider.jsx',
+            css: ['@acme/ui/styles.css'],
+            ssr: false,
+        });
+    });
+    it('finds packages and variables in a referenced root config', async () => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), { $ref: './config.json' });
+        await fse.outputJson(join(docsRoot, 'config.json'), {
+            packages: { ssr: false },
+            variables: { label: 'Synthetic label' },
+        });
+        const setup = await readPackagesSetup(docsRoot);
+        expect(setup?.packages).toEqual({ ssr: false });
+        expect(setup?.variables).toEqual({ label: 'Synthetic label' });
+    });
+    it.each([
+        { file: 'missing.json', content: undefined, message: /does not exist/ },
+        { file: 'invalid.json', content: '{', message: /contains invalid JSON/ },
+    ])('reports a broken $ref to $file as a docs config error', async ({ file, content, message }) => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            packages: { $ref: `./${file}` },
+        });
+        if (content !== undefined)
+            await fse.outputFile(join(docsRoot, file), content);
+        await expect(readPackagesSetup(docsRoot)).rejects.toThrow(DocsJsonError);
+        await expect(readPackagesSetup(docsRoot)).rejects.toThrow(message);
+    });
+    it('keeps packages disabled when docs.json is missing', async () => {
+        expect(await readPackagesSetup(docsRoot)).toBeUndefined();
+    });
+    it('keeps packages disabled without a packages key', async () => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
+        expect(await readPackagesSetup(docsRoot)).toBeUndefined();
+    });
+    it.each([
+        ['', 'docs.json could not be loaded: Unexpected end of JSON input'],
+        ['["packages"]', 'docs.json is not a JSON object'],
+    ])('rejects docs.json %j', async (raw, message) => {
+        await fse.outputFile(join(docsRoot, 'docs.json'), raw);
+        await expect(readPackagesSetup(docsRoot)).rejects.toEqual(new DocsJsonError([message]));
+    });
+    it.each([
+        ['', 'package.json is not valid JSON: Unexpected end of JSON input'],
+        ['["recharts"]', 'package.json is not a JSON object'],
+        ['null', 'package.json is not a JSON object'],
+    ])('reports package.json %j without package names', async (raw, message) => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputFile(join(docsRoot, 'package.json'), raw);
+        const setup = await readPackagesSetup(docsRoot);
+        expect(setup?.errors).toEqual([message]);
+        expect(setup?.packageJsonError).toBe(message);
+        expect(setup?.packageNames).toEqual(new Set());
+    });
+    it.each([
+        ['a string', 'nope', ['docs.json packages: Expected object, received string']],
+        [
+            'an http registry',
+            { registries: { '@acme': 'http://npm.acme.com/' } },
+            [
+                'docs.json packages.registries.@acme: Registry URLs must start with `https://` and then the host',
+            ],
+        ],
+        [
+            'a provider outside the docs',
+            { provider: '../provider.jsx', isolation: 'none' },
+            [
+                'docs.json packages.provider: Provider path cannot contain `..` segments',
+                "docs.json packages.isolation: Invalid enum value. Expected 'page' | 'frame', received 'none'",
+            ],
+        ],
+    ])('rejects %s for packages with the schema errors and the variables', async (_, packages, errors) => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            name: 'Docs',
+            packages,
+            variables: { label: 'Synthetic label' },
+        });
+        const error = await readPackagesSetup(docsRoot).catch((caught) => caught);
+        expect(error).toBeInstanceOf(InvalidPackagesError);
+        if (!(error instanceof InvalidPackagesError))
+            return;
+        expect(error.problems).toEqual(errors);
+        expect(error.variables).toEqual({ label: 'Synthetic label' });
+    });
+    it('reports errors in a snippet a page imports', async () => {
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), 'import { Chart } from "/snippets/chart.jsx";\n\n<Chart />\n');
+        await fse.outputFile(join(docsRoot, 'snippets/chart.jsx'), 'import { Button } from "@acme/ui";\n\nexport const Chart = () => <Button\n');
+        const collected = await collectPackageIslands({
+            docsRoot,
+            packageNames: new Set(['@acme/ui']),
+        });
+        expect(collected.errors.some(({ file }) => file === 'snippets/chart.jsx')).toBe(true);
+    });
+});

package/dist/index.d.ts

@@ -6,4 +6,5 @@ import validateBuild from './local-preview/validate-build.js';
 import { getClientVersion } from './util.js';
 export * from './logs.js';
 export * from './logging-state.js';
+export * from './packages/index.js';
 export { dev, exportSite, validateBuild, getClientVersion, getLatestClientVersion, downloadTargetMint, getVersionMap, LOCAL_LINKED_CLI_VERSION, };

package/dist/index.js

@@ -6,4 +6,5 @@ import validateBuild from './local-preview/validate-build.js';
 import { getClientVersion } from './util.js';
 export * from './logs.js';
 export * from './logging-state.js';
+export * from './packages/index.js';
 export { dev, exportSite, validateBuild, getClientVersion, getLatestClientVersion, downloadTargetMint, getVersionMap, LOCAL_LINKED_CLI_VERSION, };

package/dist/local-preview/index.js

@@ -6,8 +6,10 @@ import pathUtil from 'path';
 import { CLIENT_PATH, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, PREVIEW_PATH, configurePreviewPath, } from '../constants.js';
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog } from '../logs.js';
+import { isNativePackagesEnabled } from '../packages/flag.js';
 import { seedPreviewFromShared } from '../util.js';
 import { timeDev, timeDevSync } from './dev-timing.js';
+import { startPackagesDev } from './packages/index.js';
 import { acquirePreviewLock } from './preview-lock.js';
 import { run } from './run.js';
 import { silentUpdateClient } from './update.js';
@@ -88,6 +90,7 @@ const startDev = async (argv) => {
     timeDevSync('switch to local client directory', () => {
         process.chdir(CLIENT_PATH);
     });
+    const nativePackages = isNativePackagesEnabled();
     let fileImportsMap;
     try {
         const result = await timeDev('prebuild content', () => prebuild(CMD_EXEC_PATH, {
@@ -97,6 +100,7 @@ const startDev = async (argv) => {
             disablePrefetch,
             allowSourceRefs: true,
             lazyPages: true,
+            nativePackages,
         }));
         fileImportsMap = result?.fileImportsMap;
     }
@@ -107,6 +111,8 @@ const startDev = async (argv) => {
         await new Promise((resolve) => setTimeout(resolve, 50));
         process.exit(1);
     }
+    if (nativePackages)
+        await timeDev('build npm packages', () => startPackagesDev());
     await timeDev('start preview runtime', () => run({ ...argv, needsUpdate, fileImportsMap }));
 };
 const dev = async (argv) => {

package/dist/local-preview/listener/index.d.ts

@@ -6,6 +6,7 @@ type LocalPreviewOptions = {
     disablePrefetch?: boolean;
     allowSourceRefs?: boolean;
     lazyPages?: boolean;
+    nativePackages?: boolean;
 };
 declare const listener: (triggerRefresh: () => void, options?: LocalPreviewOptions, gate?: Promise<void>) => void;
 declare const initializeFrontmatterHashCache: () => Promise<void>;