@nerest/nerest 0.0.9 → 1.5.0

package/dist/client/index.js

@@ -7,8 +7,8 @@ import ReactDOM from 'react-dom/client';
 // if needed.
 const modules = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
 async function runHydration() {
-    for (const container of document.querySelectorAll('div[data-app-name]')) {
-        const appName = container.getAttribute('data-app-name');
+    for (const container of document.querySelectorAll(`div[data-project-name="${import.meta.env.NEREST_PROJECT_NAME}"]`)) {
+        const appName = container.getAttribute(`data-app-name`);
         const appModuleLoader = modules[`/apps/${appName}/index.tsx`];
         if (!appModuleLoader || container.hasAttribute('data-app-hydrated')) {
             continue;
@@ -24,9 +24,16 @@ async function runHydration() {
         ReactDOM.hydrateRoot(container, reactElement);
     }
 }
+// Apps can only be hydrated after DOM is ready, because we need to query
+// apps' containers and their corresponding scripts.
 if (document.readyState !== 'complete') {
     document.addEventListener('DOMContentLoaded', runHydration);
 }
 else {
     runHydration();
 }
+// Entries might be self-initializing (e.g. client-only apps) or have other
+// side effects. In that case we have to load them eagerly, so that their
+// initialization code can run, even if there is nothing to hydrate.
+const clientSideEffects = JSON.parse(import.meta.env.NEREST_CLIENT_SIDE_EFFECTS);
+clientSideEffects?.forEach((name) => modules[`/apps/${name}/index.tsx`]?.());

package/dist/server/development.d.ts

@@ -1 +1 @@
-export declare function runDevelopmentServer(): Promise<void>;
+export declare function runDevelopmentServer(port: number): Promise<void>;

package/dist/server/development.js

@@ -1,150 +1,72 @@
 // This is the nerest development server entrypoint
 import path from 'path';
-import { build, createServer } from 'vite';
-import fastify from 'fastify';
+import { build, createServer as createViteServer } from 'vite';
 import fastifyStatic from '@fastify/static';
-import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
-import { loadApps } from './parts/apps.js';
-import { renderApp } from './parts/render.js';
-import { renderPreviewPage } from './parts/preview.js';
-import { validator } from './parts/validator.js';
-import { setupSwagger } from './parts/swagger.js';
-import { setupK8SProbes } from './parts/k8s-probes.js';
-import { runRuntimeHook } from './hooks/runtime.js';
-import { runPropsHook } from './hooks/props.js';
-// eslint-disable-next-line max-statements
-export async function runDevelopmentServer() {
+import fastifyMiddie from '@fastify/middie';
+import { createServer } from './shared.js';
+import { viteConfigDevelopmentClient, viteConfigDevelopmentServer, } from '../build/configs/development.js';
+import { loadBuildConfig } from './loaders/build.js';
+import { loadApps } from './loaders/apps.js';
+import { loadProject } from './loaders/project.js';
+export async function runDevelopmentServer(port) {
     const root = process.cwd();
-    // TODO: move build config into a separate file
-    // TODO: look at @vitejs/plugin-react (everything seems fine without it though)
-    // TODO: look at @vitejs/plugin-legacy (needed for browsers without module support)
-    const config = {
-        root,
-        appType: 'custom',
-        envPrefix: 'NEREST_',
-        server: { middlewareMode: true },
-        build: {
-            // Manifest is needed to report used assets in SSR handles
-            manifest: true,
-            modulePreload: false,
-            // TODO: watch is only necessary for the client build
-            watch: {},
-            rollupOptions: {
-                input: '/node_modules/@nerest/nerest/client/index.ts',
-                output: {
-                    dir: 'build',
-                    entryFileNames: `client/assets/[name].js`,
-                    chunkFileNames: `client/assets/[name].js`,
-                    assetFileNames: `client/assets/[name].[ext]`,
-                },
-            },
-        },
-        // TODO: this doesn't seem to work without the index.html file entry and
-        // produces warnings in dev mode. look into this maybe
-        optimizeDeps: {
-            disabled: true,
-        },
-    };
+    // Allow overriding STATIC_PATH in development, useful for debugging
+    // micro frontend from another device on the same local network
+    let staticPath = process.env.STATIC_PATH || `http://127.0.0.1:${port}/`;
+    if (!staticPath.endsWith('/')) {
+        staticPath += '/';
+    }
+    // Generate vite configuration with nerest/build.json applied
+    const buildConfig = await loadBuildConfig(root);
+    // Load project meta details
+    const project = await loadProject(root);
     // Build the clientside assets and watch for changes
-    // TODO: this should probably be moved from here
-    await startClientBuildWatcher(config);
-    // Load app entries following the `apps/{name}/index.tsx` convention
-    // TODO: remove hardcoded port
-    const apps = await loadApps(root, 'http://0.0.0.0:3000/');
+    await startClientBuildWatcher(await viteConfigDevelopmentClient({
+        root,
+        base: staticPath,
+        buildConfig,
+        project,
+    }));
     // Start vite server that will be rendering SSR components
-    const viteSsr = await createServer(config);
-    const app = fastify();
-    // Setup schema validation. We have to use our own ajv instance that
-    // we can use both to validate request bodies and examples against
-    // app schemas
-    app.setValidatorCompiler(({ schema }) => validator.compile(schema));
-    await setupSwagger(app);
-    for (const appEntry of Object.values(apps)) {
-        const { name, entry, propsHookEntry, examples, schema } = appEntry;
-        const routeOptions = {};
-        // TODO: report error if schema is missing, unless this app is client-only
-        if (schema) {
-            routeOptions.schema = {
-                // Use description as Swagger summary, since summary is visible
-                // even when the route is collapsed in the UI
-                summary: schema.description,
-                body: {
-                    ...schema,
-                    // Mix examples into the schema so they become accessible
-                    // in the Swagger UI
-                    examples: Object.values(examples),
-                },
-            };
-        }
-        // POST /api/{name} -> render app with request.body as props
-        app.post(`/api/${name}`, routeOptions, async (request) => {
-            // ssrLoadModule drives the "hot-reload" logic, and allows
-            // picking up changes to the source without restarting the server
-            const ssrComponent = await viteSsr.ssrLoadModule(entry, {
-                fixStacktrace: true,
-            });
-            const props = await runPropsHook(request.body, () => viteSsr.ssrLoadModule(propsHookEntry));
-            return renderApp({
-                name,
-                assets: appEntry.assets,
-                component: ssrComponent.default,
-            }, props);
-        });
-        for (const [exampleName, example] of Object.entries(examples)) {
-            // Validate example against schema when specified
-            if (schema && !validator.validate(schema, example)) {
-                // TODO: use logger and display errors more prominently
-                console.error(`Example "${exampleName}" of app "${name}" does not satisfy schema: ${validator.errorsText()}`);
-            }
-            // GET /api/{name}/examples/{example} -> render a preview page
-            // with a predefined example body
-            const exampleRoute = `/api/${name}/examples/${exampleName}`;
-            app.get(exampleRoute, {
-                schema: {
-                    // Add a clickable link to the example route in route's Swagger
-                    // description so it's easier to navigate to
-                    description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
-                },
-            }, async (_, reply) => {
-                const ssrComponent = await viteSsr.ssrLoadModule(entry, {
-                    fixStacktrace: true,
-                });
-                const props = await runPropsHook(example, () => viteSsr.ssrLoadModule(propsHookEntry));
-                const { html, assets } = renderApp({
-                    name,
-                    assets: appEntry.assets,
-                    component: ssrComponent.default,
-                }, props);
-                reply.type('text/html');
-                return renderPreviewPage(html, assets);
-            });
-        }
-    }
-    // Add graceful shutdown handler to prevent requests errors
-    await app.register(fastifyGracefulShutdown);
-    if (process.env.ENABLE_K8S_PROBES) {
-        await setupK8SProbes(app);
-    }
-    // TODO: only do this locally, load from CDN in production
+    const viteSsr = await createViteServer(await viteConfigDevelopmentServer({
+        root,
+        base: staticPath,
+        buildConfig,
+        project,
+    }));
+    // Load app entries following the `apps/{name}/index.tsx` convention
+    const apps = await loadApps(root, staticPath);
+    const app = await createServer({
+        root,
+        project,
+        apps,
+        // ssrLoadModule picks up the changes without restarting the server
+        loadComponent: async (entry) => (await viteSsr.ssrLoadModule(`/apps/${entry}/index.tsx`, {
+            fixStacktrace: true,
+        })).default,
+        loadPropsHook: (entry) => viteSsr.ssrLoadModule(`/apps/${entry}/props.ts`),
+        loadRuntimeHook: () => viteSsr.ssrLoadModule('/nerest/runtime.ts'),
+    });
+    // Register middie to use vite's Connect-style middlewares
+    await app.register(fastifyMiddie);
+    app.use(viteSsr.middlewares);
+    // @fastify/static is only used locally for development, in production static
+    // files are served from STATIC_PATH, which is usually a CDN location
     await app.register(fastifyStatic, {
-        root: path.join(root, 'build'),
-        // TODO: maybe use @fastify/cors instead
+        root: path.join(root, 'build/client/assets'),
+        // Set CORS headers so the development server assets can be accessed from
+        // remote devices, e.g. mobile phones
         setHeaders(res) {
             res.setHeader('Access-Control-Allow-Origin', '*');
             res.setHeader('Access-Control-Allow-Methods', 'GET');
             res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With, content-type, Authorization');
         },
     });
-    // Execute runtime hook in nerest-runtime.ts if it exists
-    await runRuntimeHook(app, () => viteSsr.ssrLoadModule('/nerest-runtime.ts'));
-    // TODO: remove hardcoded port
     await app.listen({
         host: '0.0.0.0',
-        port: 3000,
+        port,
     });
-    console.log('Nerest is listening on 0.0.0.0:3000');
 }
-// TODO: this should probably be moved from here
 async function startClientBuildWatcher(config) {
     const watcher = (await build(config));
     return new Promise((resolve) => {

package/dist/server/hooks/logger.d.ts

@@ -0,0 +1 @@
+export declare function runLoggerHook(loader: () => Promise<unknown>): Promise<boolean | (import("fastify").FastifyLoggerOptions<import("fastify").RawServerDefault, import("fastify").FastifyRequest<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown, import("fastify").FastifyBaseLogger, import("fastify/types/type-provider.js").ResolveFastifyRequestType<import("fastify").FastifyTypeProviderDefault, import("fastify").FastifySchema, import("fastify").RouteGenericInterface>>, import("fastify").FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>> & import("fastify/types/logger.js").PinoLoggerOptions) | null | undefined>;

package/dist/server/hooks/logger.js

@@ -0,0 +1,24 @@
+// Load the runtime hook module and run it if it exists, to receive
+// logger configuration. If the `logger` function does not exist
+// in the module, ignore it and use default configuration.
+export async function runLoggerHook(loader) {
+    let module;
+    try {
+        module = (await loader());
+    }
+    catch { }
+    if (typeof module?.logger === 'function') {
+        // If module exists and exports a logger function, execute it
+        try {
+            return module.logger();
+        }
+        catch (e) {
+            // Allow console.error here, because we can't app.log the error if we
+            // can't create the logger in the first place.
+            // eslint-disable-next-line no-console
+            console.error('Failed to load logger configuration', e);
+            process.exit(1);
+        }
+    }
+    return null;
+}

package/dist/server/hooks/props.d.ts

@@ -1 +1,2 @@
-export declare function runPropsHook(props: unknown, loader: () => Promise<unknown>): Promise<Record<string, unknown>>;
+import type { FastifyInstance } from 'fastify';
+export declare function runPropsHook(app: FastifyInstance, loader: () => Promise<unknown>, props: unknown): Promise<Record<string, unknown>>;

package/dist/server/hooks/props.js

@@ -1,12 +1,14 @@
 // Load the props hook module and run it if it exists, passing down app's
-// props object. This hook can be used to modify props before they are passed
-// to the root app component.
-export async function runPropsHook(props, loader) {
+// props object and logger. This hook can be used to modify props before
+// they are passed to the root app component.
+export async function runPropsHook(app, loader, props) {
     let module;
     try {
         module = (await loader());
     }
     catch { }
     // If module exists and exports a default function, run it to modify props
-    return (typeof module?.default === 'function' ? module.default(props) : props);
+    return (typeof module?.default === 'function'
+        ? module.default(props, app.log)
+        : props);
 }

package/dist/server/hooks/runtime.js

@@ -14,15 +14,15 @@ export async function runRuntimeHook(app, loader) {
             await module.default(app);
         }
         catch (e) {
-            console.error('Failed to execute runtime hook', e);
+            app.log.fatal('Failed to execute runtime hook', e);
             process.exit(1);
         }
     }
     else if (module) {
-        console.error("Runtime hook found, but doesn't export default function!");
+        app.log.fatal("Runtime hook found, but doesn't export default function!");
         process.exit(1);
     }
     else {
-        console.log('Runtime hook not found, skipping...');
+        app.log.info('Runtime hook not found, skipping...');
     }
 }

package/dist/server/{parts → loaders}/apps.d.ts

@@ -1,3 +1,4 @@
+import type { JSONSchema } from '@apidevtools/json-schema-ref-parser';
 export type AppEntry = {
     name: string;
     root: string;
@@ -5,7 +6,7 @@ export type AppEntry = {
     propsHookEntry: string;
     assets: string[];
     examples: Record<string, unknown>;
-    schema: Record<string, unknown> | null;
+    schema: JSONSchema | null;
 };
 export declare function loadApps(root: string, deployedStaticPath: string): Promise<{
     [k: string]: AppEntry;

package/dist/server/loaders/apps.js

@@ -0,0 +1,36 @@
+import path from 'path';
+import fg from 'fast-glob';
+import { loadAppAssets } from './assets.js';
+import { loadAppExamples } from './examples.js';
+import { loadAppSchema } from './schema.js';
+import { loadViteManifest } from './manifest.js';
+// Build the record of the available apps by convention
+// apps -> /apps/{name}/index.tsx
+// examples -> /apps/{name}/examples/{example}.json
+export async function loadApps(root, deployedStaticPath) {
+    const manifest = await loadViteManifest(root);
+    const appBase = path.join(root, 'apps');
+    const appPattern = `${fg.convertPathToPattern(appBase)}/*`;
+    const appDirs = await fg.glob(appPattern, { onlyDirectories: true });
+    const apps = [];
+    for (const appDir of appDirs) {
+        apps.push(await loadApp(appDir, manifest, deployedStaticPath));
+    }
+    return Object.fromEntries(apps);
+}
+async function loadApp(appDir, manifest, deployedStaticPath) {
+    // TODO: report problems with loading entries, assets and/or examples
+    const name = path.basename(appDir);
+    return [
+        name,
+        {
+            name,
+            root: appDir,
+            entry: path.join(appDir, 'index.tsx'),
+            propsHookEntry: path.join(appDir, 'props.ts'),
+            assets: loadAppAssets(name, manifest, deployedStaticPath),
+            examples: await loadAppExamples(appDir),
+            schema: await loadAppSchema(appDir),
+        },
+    ];
+}

package/dist/server/loaders/assets.js

@@ -5,6 +5,29 @@ export function loadAppAssets(appName, manifest, staticPath) {
     // that are used on the page based on their name
     const clientEntryJs = manifest['node_modules/@nerest/nerest/client/index.ts'].file;
     // Each app has its own CSS bundles, if it imports any CSS
-    const appCss = manifest[`apps/${appName}/index.tsx`].css ?? [];
-    return [clientEntryJs, ...appCss].map((x) => staticPath + x);
+    const appCss = collectCssUrls(manifest, `apps/${appName}/index.tsx`);
+    return [clientEntryJs, ...appCss].map((x) => new URL(x, staticPath).href);
+}
+// Collects all CSS URLs by walking the manifest tree of static imports
+// for a specific entry. These CSS chunks are loaded dynamically by Vite,
+// but we need to inject them into the page statically to prevent a flash
+// of unstyled content
+function collectCssUrls(manifest, entryName) {
+    const cssUrls = new Set();
+    const scannedEntries = new Set([entryName]);
+    const queue = [entryName];
+    while (queue.length > 0) {
+        const entry = queue.shift();
+        const manifestEntry = manifest[entry];
+        if (manifestEntry) {
+            manifestEntry.css?.forEach((url) => cssUrls.add(url));
+            manifestEntry.imports?.forEach((name) => {
+                if (!scannedEntries.has(name)) {
+                    scannedEntries.add(name);
+                    queue.push(name);
+                }
+            });
+        }
+    }
+    return cssUrls;
 }

package/dist/server/loaders/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildConfiguration } from '../../schemas/nerest-build.schema.js';
+export declare function loadBuildConfig(root: string): Promise<BuildConfiguration | undefined>;

package/dist/server/loaders/build.js

@@ -0,0 +1,11 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+// TODO: error handling
+export async function loadBuildConfig(root) {
+    const configPath = path.join(root, 'nerest/build.json');
+    if (existsSync(configPath)) {
+        const content = await fs.readFile(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+}

package/dist/server/loaders/examples.js

@@ -1,24 +1,18 @@
 import path from 'path';
-import { existsSync } from 'fs';
 import fs from 'fs/promises';
+import fg from 'fast-glob';
 // Loads and parses the example json files for providing
 // `/examples/` routes of the dev server
 export async function loadAppExamples(appRoot) {
-    const examplesRoot = path.join(appRoot, 'examples');
-    // Examples are optional and may not exist
-    if (!existsSync(examplesRoot)) {
-        return {};
-    }
-    const exampleFiles = (await fs.readdir(examplesRoot, { withFileTypes: true }))
-        .filter((d) => d.isFile() && d.name.endsWith('.json'))
-        .map((d) => d.name);
+    const exampleBase = path.join(appRoot, 'examples');
+    const examplePattern = `${fg.convertPathToPattern(exampleBase)}/*.json`;
+    const exampleFiles = await fg.glob(examplePattern, { onlyFiles: true });
     const examples = {};
     // TODO: error handling and reporting
-    for (const filename of exampleFiles) {
-        const file = path.join(examplesRoot, filename);
-        const content = await fs.readFile(file, { encoding: 'utf8' });
+    for (const filePath of exampleFiles) {
+        const content = await fs.readFile(filePath, 'utf-8');
         const json = JSON.parse(content);
-        examples[path.basename(filename, '.json')] = json;
+        examples[path.basename(filePath, '.json')] = json;
     }
     return examples;
 }

package/dist/server/loaders/manifest.d.ts

@@ -1 +1,8 @@
-export declare function loadAppManifest(root: string): Promise<any>;
+import type { Manifest as ViteManifest } from 'vite';
+import type { Project } from './project.js';
+import type { AppEntry } from './apps.js';
+export declare function loadViteManifest(root: string): Promise<ViteManifest>;
+export declare function loadNerestManifest(root: string): Promise<{
+    project: Project;
+    apps: Record<string, AppEntry>;
+}>;

package/dist/server/loaders/manifest.js

@@ -1,10 +1,18 @@
 import path from 'path';
 import fs from 'fs/promises';
-// Manifest is used to provide assets list for every app
+// Vite manifest is used to provide assets list for every app
 // for use with SSR
-export async function loadAppManifest(root) {
+export async function loadViteManifest(root) {
     // TODO: error handling
-    const manifestPath = path.join(root, 'build', 'manifest.json');
-    const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
+    const manifestPath = path.join(root, 'build/client/assets/.vite/manifest.json');
+    const manifestData = await fs.readFile(manifestPath, 'utf-8');
+    return JSON.parse(manifestData);
+}
+// Nerest manifest contains info about the whole project
+// and every app within it
+export async function loadNerestManifest(root) {
+    // TODO: error handling
+    const manifestPath = path.join(root, 'build/nerest-manifest.json');
+    const manifestData = await fs.readFile(manifestPath, 'utf-8');
     return JSON.parse(manifestData);
 }

package/dist/server/loaders/preview.d.ts

@@ -0,0 +1,4 @@
+export type PreviewParts = {
+    head: string;
+};
+export declare function loadPreviewParts(root: string): Promise<PreviewParts>;

package/dist/server/loaders/preview.js

@@ -0,0 +1,11 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import fs from 'fs/promises';
+export async function loadPreviewParts(root) {
+    let head = '';
+    const headPath = path.join(root, 'nerest/preview-head.html');
+    if (existsSync(headPath)) {
+        head = await fs.readFile(headPath, 'utf-8');
+    }
+    return { head };
+}

package/dist/server/loaders/project.d.ts

@@ -0,0 +1,16 @@
+export type Project = {
+    name: string;
+    description?: string;
+    version?: string;
+    homepage?: string;
+    repository?: string | {
+        url?: string;
+    };
+};
+export declare function loadProject(root: string): Promise<{
+    name: any;
+    description: any;
+    version: any;
+    homepage: any;
+    repository: any;
+}>;

package/dist/server/loaders/project.js

@@ -0,0 +1,11 @@
+import path from 'path';
+import fs from 'fs/promises';
+// Loads project meta information and available apps
+export async function loadProject(root) {
+    const packageJson = await fs.readFile(path.join(root, 'package.json'), 'utf-8');
+    const { name = '', description, version, homepage, repository, } = JSON.parse(packageJson);
+    if (!name) {
+        console.warn('"name" is not set in package.json, this may cause conflicts when hydrating multiple apps from different micro frontends');
+    }
+    return { name, description, version, homepage, repository };
+}

package/dist/server/loaders/schema.d.ts

@@ -1 +1,2 @@
-export declare function loadAppSchema(appRoot: string): Promise<any>;
+import RefParser from '@apidevtools/json-schema-ref-parser';
+export declare function loadAppSchema(appRoot: string): Promise<RefParser.JSONSchema | null>;

package/dist/server/loaders/schema.js

@@ -1,14 +1,18 @@
 import path from 'path';
 import { existsSync } from 'fs';
-import fs from 'fs/promises';
+import RefParser from '@apidevtools/json-schema-ref-parser';
 // Loads and parses the schema file for a specific app
 export async function loadAppSchema(appRoot) {
     const schemaPath = path.join(appRoot, 'schema.json');
-    let schema = null;
-    // TODO: error handling and reporting
-    if (existsSync(schemaPath)) {
-        const file = await fs.readFile(schemaPath, { encoding: 'utf-8' });
-        schema = JSON.parse(file);
-    }
-    return schema;
+    // We are using dereference to resolve $refs in schema files and
+    // to resolve relative dependencies between schemas. The resolved
+    // schema will be stringified and saved in the build manifest,
+    // so we need it to have no circular references.
+    return existsSync(schemaPath)
+        ? RefParser.dereference(schemaPath, {
+            dereference: {
+                circular: false,
+            },
+        })
+        : null;
 }

package/dist/server/parts/k8s-probes.js

@@ -7,16 +7,20 @@ export async function setupK8SProbes(app) {
     // - finishes all current requests
     // - shuts down the server
     let isShutdownInProgress = false;
-    app.gracefulShutdown((code, next) => {
-        // TODO: replace with nerest logger, when it'll be ready
-        console.log('Graceful shutdown in process...');
+    app.gracefulShutdown(() => {
+        app.log.info('Graceful shutdown in process...');
         isShutdownInProgress = true;
-        next();
     });
-    app.get('/livenessProbe', { logLevel: 'silent' }, (req, res) => {
+    app.get('/livenessProbe', {
+        schema: { tags: ['@service'] },
+        logLevel: 'silent',
+    }, (req, res) => {
         res.status(200).send();
     });
-    app.get('/readinessProbe', { logLevel: 'silent' }, (req, res) => {
+    app.get('/readinessProbe', {
+        schema: { tags: ['@service'] },
+        logLevel: 'silent',
+    }, (req, res) => {
         if (isShutdownInProgress) {
             res.status(503).send({ status: 'Shutdown in progress' });
         }

package/dist/server/parts/preview.d.ts

@@ -1 +1,2 @@
-export declare function renderPreviewPage(html: string, assets: string[]): string;
+import type { PreviewParts } from '../loaders/preview.js';
+export declare function renderPreviewPage(html: string, assets: string[], parts: PreviewParts): string;

package/dist/server/parts/preview.js

@@ -1,10 +1,14 @@
 // Renders the preview page available by convention at /api/{name}/examples/{example}
-export function renderPreviewPage(html, assets) {
+export function renderPreviewPage(html, assets, parts) {
     const { scripts, styles } = mapAssets(assets);
     return `
+  <!DOCTYPE html>
   <html>
   <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
     ${styles.join('\n')}
+    ${parts.head}
   </head>
   <body>
     ${html}
@@ -14,9 +18,6 @@ export function renderPreviewPage(html, assets) {
   `;
 }
 function mapAssets(assets) {
-    // TODO: script type="module" is not supported by older browsers
-    // but vite doesn't provide `nomodule` fallback by default
-    // see @vitejs/plugin-legacy
     const scripts = assets
         .filter((src) => src.endsWith('.js'))
         .map((src) => `<script type="module" src="${src}"></script>`);