improve logging

Author: junzyx

.changeset/gold-onions-kneel.md

@@ -0,0 +1,9 @@
+---
+"htmldocs-starter": patch
+"htmldocs": patch
+"@htmldocs/render": patch
+"@htmldocs/react": patch
+"@htmldocs/examples": patch
+---
+
+improve logging, dev experience

packages/htmldocs/README.md

@@ -0,0 +1,109 @@
+![htmldocs](https://github.com/user-attachments/assets/6f8e8ef2-022d-4418-8e86-c9663587f92f)
+
+<div align="center"><strong>htmldocs</strong></div>
+<div align="center">Build beautiful, reactive documents with modern web technologies <br /> and generate them at scale. Batteries included.</div>
+<br />
+<div align="center">
+<a href="https://htmldocs.com">Website</a> 
+<span> · </span>
+<a href="https://github.com/htmldocs-js/htmldocs">GitHub</a> 
+<span> · </span>
+<a href="https://join.slack.com/t/htmldocs/shared_invite/zt-29hw1bnmu-ShX6Jo1KNc_XeF~gFQJH_Q">Slack</a>
+</div>
+
+## Introduction
+PDF document creation is stuck in the past - from clunky Word docs to complex LaTeX to outdated tools. htmldocs brings document generation into 2025 with a modern developer experience using the tools you already love: <b>React</b>, <b>TypeScript</b>, and <b>Tailwind</b>.
+
+## Why
+
+htmldocs is a modern toolkit for building documents with the web:
+
+- **Styling**: Use modern CSS properties to create visually stunning documents with web-like flexibility.
+
+- **Structure**: Create clean layouts using HTML's powerful tools like flexbox, grid, and tables.
+
+- **External Libraries**: Seamlessly integrate web libraries like FontAwesome, Bootstrap, and KaTeX
+
+- **Dynamic Templates**: Leverage JSX to create reusable document templates with dynamic content:
+  ```jsx
+  function Invoice({ customer, items, total }) {
+    return (
+      <Document>
+        <Page>
+          <h1>Invoice for {customer.name}</h1>
+          {items.map(item => (
+            <LineItem {...item} />
+          ))}
+          <Total amount={total} />
+        </Page>
+      </Document>
+    );
+  }
+  ```
+
+- **Data-Driven Documents**: Generate documents programmatically by passing data through props or fetching from APIs. Perfect for invoices, contracts, and reports that need dynamic content.
+
+- **Version Control**: Track document changes using Git and other version control systems
+
+- **Consistency**: Maintain uniform document styling across your organization through shared stylesheets.
+
+## Install
+
+To create your first htmldocs project, run the following command:
+
+```sh
+npx htmldocs@latest init
+```
+
+For further instructions or to integrate htmldocs into your existing project, refer to the [Getting Started](https://docs.htmldocs.com/getting-started) guide.
+
+## Getting Started
+
+Create your first document with htmldocs:
+
+```jsx
+import { Document, Page } from "@htmldocs/react";
+
+export default function MyDocument() {
+  return (
+    <Document size="A4" orientation="portrait" margin="0.5in">
+        <Page style={{ backgroundColor: "#000", color: "#fff" }}>
+            <h1>Hello from the dark side</h1>
+        </Page>
+    </Document>
+  );
+}
+```
+
+## Components
+
+htmldocs comes with a standard set of components to help you layout and style your documents.
+
+- [Document](https://docs.htmldocs.com/components/document)
+- [Head](https://docs.htmldocs.com/components/head)
+- [Page](https://docs.htmldocs.com/components/page)
+- [Footer](https://docs.htmldocs.com/components/footer)
+- [MarginBox](https://docs.htmldocs.com/components/margin-box)
+- [Spacer](https://docs.htmldocs.com/components/spacer)
+
+## How it works
+
+htmldocs is a modern toolkit for building documents with web technologies. It automatically handles the layout and chunking of your document into pages, templating variables using JSX, and hot-reloading your document.
+
+htmldocs is built upon Chromium's rendering engine, which means it can render any HTML, CSS, and JavaScript. This is different from other tools like [wkhtmltopdf](https://wkhtmltopdf.org/), [WeasyPrint](https://weasyprint.org/), and [Prince](https://www.princexml.com/), which only support a subset of HTML and CSS.
+
+htmldocs also uses the [Paged.js library](https://pagedjs.org/) under the hood. Paged.js is used for layout and chunking, as well as more modern features like margin boxes that aren't fully supported by the W3C's CSS standard.
+
+## Tech Stack
+
+| <img src="https://nextjs.org/static/favicon/favicon-32x32.png" width="48px" height="48px" alt="Next.js"> | <img src="https://www.typescriptlang.org/favicon-32x32.png" width="48px" height="48px" alt="TypeScript"> | <img src="https://user-images.githubusercontent.com/4060187/196936123-f6e1db90-784d-4174-b774-92502b718836.png" width="48px" height="48px" alt="Turborepo"> | <img src="https://pnpm.io/img/favicon.png" width="48px" height="48px" alt="pnpm"> |
+|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| Next.js                                                                                                  | TypeScript                                                                                            | Turborepo                                                                                         | pnpm                                                                             |
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License

packages/htmldocs/package.json

@@ -74,7 +74,6 @@
     "tailwindcss": "^3.4.3",
     "tailwindcss-animate": "^1.0.7",
     "ts-json-schema-generator": "^2.2.0",
-    "winston": "^3.14.2",
     "zod": "^3.23.8"
   },
   "devDependencies": {

packages/htmldocs/src/app/actions/render-document-by-path.tsx

@@ -1,8 +1,12 @@
 'use server';
+
 import React from 'react';
 import fs from 'node:fs';
 import { getDocumentComponent } from '../../utils/get-document-component';
 import { ErrorObject, improveErrorWithSourceMap } from '@htmldocs/render';
+import logger from '../lib/logger';
+import chalk from 'chalk';
+import path from 'node:path';
 
 export interface RenderedDocumentMetadata {
   markup: string;
@@ -26,17 +30,16 @@ export const renderDocumentByPath = async (
   documentPath: string,
   props: Record<string, any> = {}
 ): Promise<DocumentRenderingResult> => {
-  const isDev = process.env.NODE_ENV === 'development';
-  isDev && console.debug(`[render] Starting render for document: ${documentPath}`);
+  logger.debug(`[render] Starting render for document: ${documentPath}`);
   const startTime = performance.now();
 
-  isDev && console.debug('[render] Loading component...');
+  logger.debug('[render] Loading component...');
   const result = await getDocumentComponent(documentPath);
   const componentLoadTime = performance.now() - startTime;
-  isDev && console.debug(`[render] Component loaded in ${componentLoadTime.toFixed(2)}ms`);
+  logger.debug(`[render] Component loaded in ${componentLoadTime.toFixed(2)}ms`);
 
   if ('error' in result) {
-    console.error('[render] Error loading component:', result.error);
+    console.error(chalk.red('[render] Error loading component:'), result.error);
     return { error: result.error };
   }
 
@@ -51,20 +54,25 @@ export const renderDocumentByPath = async (
   const DocumentComponent = Document as React.FC;
 
   try {
-    isDev && console.debug('[render] Starting rendering...');
+    logger.debug('[render] Starting rendering...');
     const renderStart = performance.now();
     const markup = await renderAsync(<DocumentComponent {...renderProps} />, documentCss);
     const renderTime = performance.now() - renderStart;
-    isDev && console.debug(`[render] Rendering completed in ${renderTime.toFixed(2)}ms`);
+    logger.debug(`[render] Rendering completed in ${renderTime.toFixed(2)}ms`);
 
-    isDev && console.debug('[render] Reading file...');
+    logger.debug('[render] Reading file...');
     const fileReadStart = performance.now();
     const reactMarkup = await fs.promises.readFile(documentPath, 'utf-8');
     const fileReadTime = performance.now() - fileReadStart;
-    isDev && console.debug(`[render] File read in ${fileReadTime.toFixed(2)}ms`);
+    logger.debug(`[render] File read in ${fileReadTime.toFixed(2)}ms`);
 
     const totalTime = performance.now() - startTime;
-    isDev && console.debug(`[render] Completed in ${totalTime.toFixed(2)}ms`);
+    logger.debug(`[render] Completed in ${totalTime.toFixed(2)}ms`);
+    const filename = path.basename(documentPath);
+    const formattedTime = totalTime >= 1000 
+      ? chalk.yellow(`${(totalTime / 1000).toFixed(2)}s`)
+      : chalk.yellow(`${totalTime.toFixed(2)}ms`);
+    console.log(`${chalk.green('✔')} Document ${chalk.cyan(filename)} rendered in ${formattedTime}`);
 
     return {
       markup,
@@ -79,7 +87,8 @@ export const renderDocumentByPath = async (
     };
   } catch (exception) {
     const error = exception as Error;
-    console.error('[render] Error during rendering:', error);
+    const filename = path.basename(documentPath);
+    console.error(`${chalk.red('✘')} Error during rendering ${chalk.cyan(filename)}:`, error);
 
     return {
       error: improveErrorWithSourceMap(

packages/htmldocs/src/app/actions/render-document-to-pdf.ts

@@ -1,6 +1,7 @@
 "use server"
 
 import { LaunchOptions, chromium } from 'playwright';
+import logger from '~/lib/logger';
 import { PageConfig, isStandardSize, parseCustomSize } from '~/lib/types';
 
 export interface RenderDocumentToPDFProps extends LaunchOptions {
@@ -28,7 +29,7 @@ export const renderDocumentToPDF = async ({
     await page.setContent(html);
     await page.waitForLoadState('networkidle');
 
-    console.debug('pageConfig', pageConfig);
+    logger.debug('pageConfig', pageConfig);
 
     const pdfOptions = {
         printBackground: true,

packages/htmldocs/src/app/components/context-editor.tsx

@@ -9,6 +9,7 @@ import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "~/component
 import { JSONSchema7 } from 'json-schema';
 import { useDocumentContext } from '~/contexts/document-context';
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "~/components/ui/dialog";
+import logger from '~/lib/logger';
 
 type DefaultValues = {
   string: string;
@@ -263,7 +264,7 @@ const ContextEditor: React.FC = () => {
   const { documentSchema, documentContext } = useDocumentContext();
 
   const numVars = Object.keys(documentSchema?.properties || {}).length;
-  console.debug({ documentSchema, documentContext });
+  logger.debug({ documentSchema, documentContext });
 
   return (
     <div className="flex flex-col gap-2 text-card-foreground">

packages/htmldocs/src/app/contexts/document-context.tsx

@@ -1,5 +1,6 @@
 import React, { createContext, useContext, useState } from 'react';
 import { JSONSchema7 } from 'json-schema';
+import logger from '~/lib/logger';
 
 interface DocumentContextValue {
   documentSchema: JSONSchema7;
@@ -32,7 +33,7 @@ export const DocumentContextProvider: React.FC<DocumentContextProviderProps> = (
 }) => {
   const [documentContext, setDocumentContext] = useState<Record<string, any>>({ document: initialDocumentPreviewProps || {} });
 
-  console.debug("Initial document context:", documentContext);
+  logger.debug("Initial document context:", documentContext);
 
   const updateDocumentContext = (path: string, newValue: any) => {
     const pathParts = path.split('.');

packages/htmldocs/src/app/contexts/documents.tsx

@@ -12,6 +12,7 @@ import {
 import { getDocumentPathFromSlug } from "~/actions/get-document-path-from-slug";
 import { renderDocumentToPDF, RenderDocumentToPDFProps } from "~/actions/render-document-to-pdf";
 import { PageConfig } from "~/lib/types";
+import logger from "~/lib/logger";
 
 const DocumentsContext = createContext<
   | {
@@ -83,6 +84,11 @@ export const DocumentsProvider = (props: {
           return;
         }
 
+        // If the document is being deleted, don't try to render it
+        if (change.event === 'unlink') {
+          continue;
+        }
+
         const slugForChangedDocument =
           // filename ex: documents/apple-receipt.tsx
           // so we need to remove the "documents/" because it isn't used
@@ -97,7 +103,7 @@ export const DocumentsProvider = (props: {
           renderingResultPerDocumentPath[pathForChangedDocument];
 
         if (typeof lastResult !== "undefined") {
-          console.debug("pathForChangedDocument", pathForChangedDocument);
+          logger.debug("pathForChangedDocument", pathForChangedDocument);
           const renderingResult = await renderDocumentByPath(
             pathForChangedDocument
           );

packages/htmldocs/src/app/hooks/use-hot-reload.ts

@@ -3,6 +3,9 @@ import { useEffect, useRef } from 'react';
 import { type Socket, io } from 'socket.io-client';
 import type { HotReloadChange } from '../../utils/types/hot-reload-change';
 
+// Create a singleton socket instance
+let globalSocket: Socket | null = null;
+
 /**
  * Hook that detects any "reload" event sent from the CLI's web socket
  * and calls the received parameter callback
@@ -11,21 +14,19 @@ export const useHotreload = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   onShouldReload: (changes: HotReloadChange[]) => any,
 ) => {
-  const socketRef = useRef<Socket | null>(null);
-
   useEffect(() => {
-    if (!socketRef.current) {
-      socketRef.current = io();
+    if (!globalSocket) {
+      globalSocket = io();
     }
-    const socket = socketRef.current;
 
-    socket.on('reload', (changes: HotReloadChange[]) => {
+    globalSocket.on('reload', (changes: HotReloadChange[]) => {
       console.log('Reloading...');
       void onShouldReload(changes);
     });
 
     return () => {
-      socket.off();
+      // Only remove this specific listener, don't disconnect the socket
+      globalSocket?.off('reload');
     };
   }, [onShouldReload]);
 };

packages/htmldocs/src/app/lib/logger.ts

@@ -0,0 +1,71 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+class Logger {
+  private static instance: Logger;
+  private currentLevel: LogLevel;
+
+  private constructor() {
+    // Default to 'info' if not set
+    this.currentLevel = (process.env.LOG_LEVEL as LogLevel) || 'info';
+  }
+
+  public static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger();
+    }
+    return Logger.instance;
+  }
+
+  public setLevel(level: LogLevel): void {
+    this.currentLevel = level;
+  }
+
+  public getLevel(): LogLevel {
+    return this.currentLevel;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    // Only log if the message's level is >= current level
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.currentLevel];
+  }
+
+  public debug(...args: any[]): void {
+    if (!this.shouldLog('debug')) {
+      return;
+    }
+    console.debug(...args);
+  }
+
+  public info(...args: any[]): void {
+    if (!this.shouldLog('info')) {
+      return;
+    }
+    console.info(...args);
+  }
+
+  public warn(...args: any[]): void {
+    if (!this.shouldLog('warn')) {
+      return;
+    }
+    console.warn(...args);
+  }
+
+  public error(...args: any[]): void {
+    if (!this.shouldLog('error')) {
+      return;
+    }
+    console.error(...args);
+  }
+}
+
+// Export a singleton instance
+const logger = Logger.getInstance();
+export default logger;
+