@formepdf/cli 0.1.0

package/dist/build.d.ts

@@ -0,0 +1,5 @@
+export interface BuildOptions {
+    output: string;
+    dataPath?: string;
+}
+export declare function buildPdf(inputPath: string, options: BuildOptions): Promise<void>;

package/dist/build.js

@@ -0,0 +1,81 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isValidElement } from 'react';
+import { bundleFile, BUNDLE_DIR } from './bundle.js';
+import { renderDocumentWithLayout } from '@formepdf/core';
+export async function buildPdf(inputPath, options) {
+    const absoluteInput = resolve(inputPath);
+    console.log(`Building ${absoluteInput}...`);
+    try {
+        const code = await bundleFile(absoluteInput);
+        // Write temp file inside CLI package dir so Node resolves @formepdf/* deps
+        const tmpFile = join(BUNDLE_DIR, `.forme-build-${Date.now()}.mjs`);
+        await writeFile(tmpFile, code);
+        try {
+            const mod = await import(pathToFileURL(tmpFile).href);
+            const element = await resolveElement(mod, options.dataPath);
+            const { pdf } = await renderDocumentWithLayout(element);
+            const outputPath = resolve(options.output);
+            await writeFile(outputPath, pdf);
+            console.log(`Written ${pdf.length} bytes to ${outputPath}`);
+        }
+        finally {
+            // Clean up temp file
+            const { unlink } = await import('node:fs/promises');
+            await unlink(tmpFile).catch(() => { });
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`\n  ${message.split('\n').join('\n  ')}\n`);
+        process.exit(1);
+    }
+}
+async function resolveElement(mod, dataPath) {
+    const exported = mod.default;
+    if (exported === undefined) {
+        throw new Error(`No default export found.\n\n` +
+            `  Your file must export a Forme element or a function that returns one:\n\n` +
+            `    export default (\n` +
+            `      <Document>\n` +
+            `        <Text>Hello</Text>\n` +
+            `      </Document>\n` +
+            `    );\n\n` +
+            `  Or with data:\n\n` +
+            `    export default function Report(data) {\n` +
+            `      return <Document><Text>{data.title}</Text></Document>\n` +
+            `    }`);
+    }
+    if (typeof exported === 'function') {
+        const data = dataPath ? await loadJsonData(dataPath) : {};
+        const result = await exported(data);
+        if (!isValidElement(result)) {
+            throw new Error(`Default export function did not return a valid Forme element.\n` +
+                `  Got: ${typeof result}\n` +
+                `  Make sure your function returns a <Document> element.`);
+        }
+        return result;
+    }
+    if (isValidElement(exported)) {
+        if (dataPath) {
+            console.warn(`Warning: --data flag provided but default export is a static element, not a function.\n` +
+                `  The data file will be ignored. Export a function to use --data.`);
+        }
+        return exported;
+    }
+    throw new Error(`Default export is not a valid Forme element.\n` +
+        `  Got: ${typeof exported}\n` +
+        `  Expected: a <Document> element or a function that returns one.`);
+}
+async function loadJsonData(dataPath) {
+    const absolutePath = resolve(dataPath);
+    const raw = await readFile(absolutePath, 'utf-8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Failed to parse data file as JSON: ${absolutePath}\n` +
+            `  Make sure the file contains valid JSON.`);
+    }
+}

package/dist/bundle.d.ts

@@ -0,0 +1,2 @@
+export declare const BUNDLE_DIR: string;
+export declare function bundleFile(filePath: string): Promise<string>;

package/dist/bundle.js

@@ -0,0 +1,87 @@
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/// The temp directory for bundled output — placed inside CLI package
+/// so that Node's module resolution finds @formepdf/react, @formepdf/core, react.
+export const BUNDLE_DIR = join(__dirname, '..');
+/// esbuild plugin that intercepts react/jsx-dev-runtime to capture source
+/// locations in a global WeakMap. React 19 no longer stores _source on
+/// elements, so we wrap jsxDEV to do it ourselves.
+const formeJsxSourcePlugin = {
+    name: 'forme-jsx-source',
+    setup(pluginBuild) {
+        pluginBuild.onResolve({ filter: /^react\/jsx-dev-runtime$/ }, () => ({
+            path: 'forme-jsx-dev-runtime',
+            namespace: 'forme-jsx',
+        }));
+        pluginBuild.onLoad({ filter: /.*/, namespace: 'forme-jsx' }, () => {
+            const cwd = pluginBuild.initialOptions.absWorkingDir || process.cwd();
+            return {
+                contents: `
+          import { jsx, Fragment } from 'react/jsx-runtime';
+          import { resolve, isAbsolute } from 'node:path';
+          export { Fragment };
+          if (!globalThis.__formeSourceMap) globalThis.__formeSourceMap = new WeakMap();
+          const _cwd = ${JSON.stringify(cwd)};
+          export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+            const el = jsx(type, props, key);
+            if (source && source.fileName) {
+              try {
+                const file = isAbsolute(source.fileName) ? source.fileName : resolve(_cwd, source.fileName);
+                globalThis.__formeSourceMap.set(el, { file, line: source.lineNumber, column: source.columnNumber });
+              } catch(e) {}
+            }
+            return el;
+          }
+        `,
+                resolveDir: cwd,
+                loader: 'js',
+            };
+        });
+    },
+};
+/// Bundle a TSX/JSX file into an ESM string that can be dynamically imported.
+export async function bundleFile(filePath) {
+    try {
+        const result = await build({
+            entryPoints: [filePath],
+            bundle: true,
+            format: 'esm',
+            platform: 'node',
+            write: false,
+            jsx: 'automatic',
+            jsxDev: true,
+            target: 'node20',
+            external: ['react', '@formepdf/react', '@formepdf/core'],
+            plugins: [formeJsxSourcePlugin],
+        });
+        return result.outputFiles[0].text;
+    }
+    catch (err) {
+        // Format esbuild errors with file location and source context
+        if (isBuildFailure(err)) {
+            const messages = [];
+            for (const error of err.errors) {
+                let loc = '';
+                if (error.location) {
+                    const { file, line, column, lineText } = error.location;
+                    loc = `  ${file}:${line}:${column}\n`;
+                    if (lineText) {
+                        loc += `  ${lineText}\n`;
+                        loc += `  ${' '.repeat(column)}^\n`;
+                    }
+                }
+                messages.push(`${error.text}\n${loc}`);
+            }
+            throw new Error(`Build error:\n${messages.join('\n')}`);
+        }
+        throw err;
+    }
+}
+function isBuildFailure(err) {
+    return (err !== null &&
+        typeof err === 'object' &&
+        'errors' in err &&
+        Array.isArray(err.errors));
+}

package/dist/dev.d.ts

@@ -0,0 +1,5 @@
+export interface DevOptions {
+    port: number;
+    dataPath?: string;
+}
+export declare function startDevServer(inputPath: string, options: DevOptions): void;

package/dist/dev.js

@@ -0,0 +1,290 @@
+import { createServer } from 'node:http';
+import { readFile, writeFile, unlink } from 'node:fs/promises';
+import { resolve, basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { watch } from 'chokidar';
+import { WebSocketServer } from 'ws';
+import open from 'open';
+import { isValidElement } from 'react';
+import { bundleFile, BUNDLE_DIR } from './bundle.js';
+import { renderPdfWithLayout } from '@formepdf/core';
+export function startDevServer(inputPath, options) {
+    const absoluteInput = resolve(inputPath);
+    const fileName = basename(absoluteInput);
+    const port = options.port;
+    const dataPath = options.dataPath ? resolve(options.dataPath) : undefined;
+    let currentPdf = null;
+    let currentLayout = null;
+    let lastRenderTime = 0;
+    let lastError = null;
+    let firstRender = true;
+    // Override state
+    let pageSizeOverride = null;
+    let inMemoryData = null;
+    let useInMemoryData = false;
+    // ── HTTP Server ──────────────────────────────────────────────
+    const server = createServer(async (req, res) => {
+        const url = req.url ?? '/';
+        if (url === '/' || url === '/index.html') {
+            const html = await getPreviewHtml();
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+        if (url === '/pdf') {
+            if (currentPdf) {
+                res.writeHead(200, {
+                    'Content-Type': 'application/pdf',
+                    'Content-Length': String(currentPdf.length),
+                });
+                res.end(currentPdf);
+            }
+            else {
+                res.writeHead(503, { 'Content-Type': 'text/plain' });
+                res.end(lastError ?? 'PDF not yet rendered');
+            }
+            return;
+        }
+        if (url === '/layout') {
+            if (currentLayout) {
+                const json = JSON.stringify(currentLayout);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(json);
+            }
+            else {
+                res.writeHead(503, { 'Content-Type': 'text/plain' });
+                res.end('Layout not yet available');
+            }
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not found');
+    });
+    // ── WebSocket ────────────────────────────────────────────────
+    const wss = new WebSocketServer({ server });
+    const clients = new Set();
+    wss.on('connection', async (ws) => {
+        clients.add(ws);
+        ws.on('close', () => clients.delete(ws));
+        // Send init message with data and page size state
+        let dataContent = null;
+        if (dataPath) {
+            try {
+                dataContent = await readFile(dataPath, 'utf-8');
+            }
+            catch { /* ignore */ }
+        }
+        const initMsg = {
+            type: 'init',
+            hasData: !!dataPath,
+            dataContent,
+            pageSizeOverride,
+        };
+        if (ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify(initMsg));
+        }
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            if (msg.type === 'setPageSize') {
+                pageSizeOverride = { width: msg.width, height: msg.height };
+                triggerRebuild();
+            }
+            if (msg.type === 'clearPageSize') {
+                pageSizeOverride = null;
+                triggerRebuild();
+            }
+            if (msg.type === 'updateData') {
+                inMemoryData = msg.data;
+                useInMemoryData = true;
+                triggerRebuild();
+            }
+            if (msg.type === 'saveData' && dataPath) {
+                const content = msg.content;
+                writeFile(dataPath, content, 'utf-8').catch((err) => {
+                    console.error(`Failed to save data file: ${err}`);
+                });
+            }
+        });
+    });
+    function broadcast(message) {
+        const data = JSON.stringify(message);
+        for (const ws of clients) {
+            if (ws.readyState === ws.OPEN) {
+                ws.send(data);
+            }
+        }
+    }
+    // ── Build + Render ───────────────────────────────────────────
+    let buildCounter = 0;
+    async function rebuild() {
+        const buildId = ++buildCounter;
+        const start = performance.now();
+        try {
+            const code = await bundleFile(absoluteInput);
+            // Skip if a newer build started
+            if (buildId !== buildCounter)
+                return;
+            // Write temp file inside CLI package dir so Node resolves @formepdf/* deps
+            const tmpFile = join(BUNDLE_DIR, `.forme-dev-${Date.now()}.mjs`);
+            await writeFile(tmpFile, code);
+            let mod;
+            try {
+                mod = await import(pathToFileURL(tmpFile).href);
+            }
+            finally {
+                await unlink(tmpFile).catch(() => { });
+            }
+            const overrideData = useInMemoryData ? inMemoryData : undefined;
+            const element = await resolveElement(mod, dataPath, overrideData);
+            // Serialize JSX to document JSON, apply overrides, then render
+            const { serialize } = await import('@formepdf/react');
+            const doc = serialize(element);
+            // Apply page size override
+            if (pageSizeOverride) {
+                const { width, height } = pageSizeOverride;
+                const customSize = { Custom: { width, height } };
+                // Override defaultPage size
+                if (doc.defaultPage && typeof doc.defaultPage === 'object') {
+                    doc.defaultPage.size = customSize;
+                }
+                // Override each Page node's config size
+                if (Array.isArray(doc.children)) {
+                    for (const child of doc.children) {
+                        if (child && typeof child === 'object' && child.kind && typeof child.kind === 'object') {
+                            const kind = child.kind;
+                            if (kind.type === 'Page' && kind.config && typeof kind.config === 'object') {
+                                kind.config.size = customSize;
+                            }
+                        }
+                    }
+                }
+            }
+            const { pdf, layout } = await renderPdfWithLayout(JSON.stringify(doc));
+            // Skip if a newer build started
+            if (buildId !== buildCounter)
+                return;
+            currentPdf = pdf;
+            currentLayout = layout;
+            lastError = null;
+            lastRenderTime = Math.round(performance.now() - start);
+            const pageCount = layout?.pages?.length ?? 0;
+            if (firstRender) {
+                firstRender = false;
+                const url = `http://localhost:${port}`;
+                console.log(`Forme dev server\n`);
+                console.log(`  Watching:  ${fileName}${dataPath ? ` + ${basename(dataPath)}` : ''}`);
+                console.log(`  Rendered:  ${pageCount} page${pageCount !== 1 ? 's' : ''} in ${lastRenderTime}ms`);
+                console.log(`  Preview:   ${url}\n`);
+                open(url);
+            }
+            else {
+                console.log(`Rebuilt in ${lastRenderTime}ms (${pageCount} page${pageCount !== 1 ? 's' : ''})`);
+            }
+            broadcast({ type: 'reload', renderTime: lastRenderTime });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            lastError = message;
+            console.error(`Build error: ${message}`);
+            broadcast({ type: 'error', message });
+        }
+    }
+    // ── File Watcher ─────────────────────────────────────────────
+    let debounceTimer = null;
+    function triggerRebuild() {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(rebuild, 100);
+    }
+    const watchPaths = [absoluteInput, ...(dataPath ? [dataPath] : [])];
+    const watcher = watch(watchPaths, { ignoreInitial: true });
+    watcher.on('change', (changedPath) => {
+        // If data file changed on disk, reset in-memory override and push new content
+        if (dataPath && resolve(changedPath) === dataPath) {
+            useInMemoryData = false;
+            inMemoryData = null;
+            readFile(dataPath, 'utf-8').then((content) => {
+                broadcast({ type: 'dataUpdate', content });
+            }).catch(() => { });
+        }
+        triggerRebuild();
+    });
+    // ── Graceful shutdown ───────────────────────────────────────
+    process.on('SIGINT', () => {
+        console.log('\nShutting down...');
+        watcher.close();
+        wss.close();
+        server.close(() => process.exit(0));
+        // Force exit after 2s if graceful shutdown stalls
+        setTimeout(() => process.exit(0), 2000);
+    });
+    // ── Start ────────────────────────────────────────────────────
+    server.listen(port, () => {
+        rebuild();
+    });
+}
+async function resolveElement(mod, dataPath, overrideData) {
+    const exported = mod.default;
+    if (exported === undefined) {
+        throw new Error(`No default export found.\n\n` +
+            `  Your file must export a Forme element or a function that returns one:\n\n` +
+            `    export default (\n` +
+            `      <Document>\n` +
+            `        <Text>Hello</Text>\n` +
+            `      </Document>\n` +
+            `    );`);
+    }
+    if (typeof exported === 'function') {
+        let data = {};
+        if (overrideData !== undefined) {
+            data = overrideData;
+        }
+        else if (dataPath) {
+            const raw = await readFile(dataPath, 'utf-8');
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`Failed to parse data file as JSON: ${dataPath}\n` +
+                    `  Make sure the file contains valid JSON.`);
+            }
+        }
+        const result = await exported(data);
+        if (!isValidElement(result)) {
+            throw new Error(`Default export function did not return a valid Forme element.\n` +
+                `  Got: ${typeof result}`);
+        }
+        return result;
+    }
+    if (isValidElement(exported)) {
+        return exported;
+    }
+    throw new Error(`Default export is not a valid Forme element.\n` +
+        `  Got: ${typeof exported}\n` +
+        `  Expected: a <Document> element or a function that returns one.`);
+}
+async function getPreviewHtml() {
+    // Try to load the preview HTML from the package's own file tree
+    const possiblePaths = [
+        // When running from dist/ (built)
+        new URL('./preview/index.html', import.meta.url),
+        // When running from src/ (dev with ts-node)
+        new URL('../src/preview/index.html', import.meta.url),
+    ];
+    for (const p of possiblePaths) {
+        try {
+            return await readFile(p, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+    }
+    // Inline fallback
+    return `<!DOCTYPE html><html><body><h1>Preview HTML not found</h1></body></html>`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { startDevServer } from './dev.js';
+import { buildPdf } from './build.js';
+const USAGE = `
+forme - Page-native PDF rendering engine
+
+Usage:
+  forme dev <file.tsx>    Start dev server with live preview
+  forme build <file.tsx>  Render PDF to disk
+
+Options:
+  -o, --output <path>     Output PDF path (build only, default: output.pdf)
+  -d, --data <path>       JSON data file to pass to template function
+  -p, --port <number>     Dev server port (default: 4242)
+  -h, --help              Show this help message
+
+Examples:
+  forme dev src/invoice.tsx
+  forme build src/invoice.tsx -o invoice.pdf
+  forme build src/report.tsx --data data.json -o report.pdf
+
+Data flag:
+  If your template exports a function instead of a JSX element,
+  use --data to pass a JSON file as the function argument:
+
+    // report.tsx
+    export default function Report(data: { title: string }) {
+      return <Document><Text>{data.title}</Text></Document>
+    }
+
+    forme build report.tsx --data '{"title": "Q4 Report"}'
+`;
+function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            output: { type: 'string', short: 'o', default: 'output.pdf' },
+            data: { type: 'string', short: 'd' },
+            port: { type: 'string', short: 'p', default: '4242' },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    if (values.help || positionals.length === 0) {
+        console.log(USAGE.trim());
+        process.exit(0);
+    }
+    const [command, inputPath] = positionals;
+    if (!inputPath) {
+        console.error(`Error: Missing input file.\n`);
+        console.log(USAGE.trim());
+        process.exit(1);
+    }
+    // Validate input file exists
+    const absoluteInput = resolve(inputPath);
+    if (!existsSync(absoluteInput)) {
+        console.error(`Error: Input file not found: ${absoluteInput}`);
+        process.exit(1);
+    }
+    // Validate data file exists if provided
+    const dataPath = values.data;
+    if (dataPath) {
+        const absoluteData = resolve(dataPath);
+        if (!existsSync(absoluteData)) {
+            console.error(`Error: Data file not found: ${absoluteData}`);
+            process.exit(1);
+        }
+    }
+    switch (command) {
+        case 'dev':
+            startDevServer(inputPath, { port: Number(values.port), dataPath });
+            break;
+        case 'build':
+            buildPdf(inputPath, { output: values.output, dataPath });
+            break;
+        default:
+            console.error(`Unknown command: ${command}\n`);
+            console.log(USAGE.trim());
+            process.exit(1);
+    }
+}
+main();