From 3767588f37e3e80d0febe54c12ab7c8fe87db73b Mon Sep 17 00:00:00 2001 From: shitianfang <61344989+shitianfang@users.noreply.github.com> Date: Fri, 26 Sep 2025 19:42:10 +0000 Subject: [PATCH 1/7] add zero-build --- README.md | 135 ++++++++++++++++++ apps/examples/documents/templates/Invoice.tsx | 2 +- dev-workflow.js | 64 +++++++++ dev.sh | 53 +++++++ package.json | 1 + 5 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 dev-workflow.js create mode 100755 dev.sh diff --git a/README.md b/README.md index 98e74ef..d9a52f1 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ htmldocs is a local document editor and preview server to help you _create_ PDFs - 🔗 Full TypeScript support for type safety - ⚡ Dynamic data integration through props and APIs - 📊 Real-time preview server with hot reloading +- 🚀 **Zero-build development** - modify templates and see changes instantly +- 🏗️ **Monorepo architecture** with pnpm workspaces and Turbo +- 🔄 **Workspace dependencies** - automatic linking between packages ## Example @@ -60,6 +63,76 @@ 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. +## Development Workflow + +htmldocs supports a **zero-build development experience** for rapid template iteration. You can modify template files and see changes instantly without any build step. + +### One-Click Development + +For the fastest setup, use our development script: + +```bash +# Start zero-build development (from project root) +./dev.sh + +# Or using npm/pnpm script +pnpm dev:zero-build +``` + +This script will: +- ✅ Install tsx if needed +- ✅ Build core dependencies (one-time) +- ✅ Start development server with hot reload +- ✅ Open examples at http://localhost:3000 + +### Manual Setup + +```bash +# 1. Install dependencies +pnpm install + +# 2. Build core dependencies (one-time only) +cd packages/react && pnpm build +cd ../render && pnpm build + +# 3. Install TypeScript runner +npm install -g tsx + +# 4. Start zero-build development +cd packages/htmldocs +tsx src/cli/index.ts dev --dir ../../apps/examples/documents +``` + +### What You Can Edit Without Building + +- ✅ **Template files** (`*.tsx` documents) - hot reload enabled +- ✅ **Next.js app** (`packages/htmldocs/src/app/*`) - hot reload enabled +- ✅ **CLI logic** (`packages/htmldocs/src/cli/*`) - restart to see changes +- ✅ **Styles** (CSS, Tailwind) - hot reload enabled + +### What Requires Building + +- ⚠️ **React components** (`packages/react/`) - run `pnpm build` after changes +- ⚠️ **Render engine** (`packages/render/`) - run `pnpm build` after changes + +### Development Commands + +```bash +# Start development with hot reload +tsx src/cli/index.ts dev --dir ../../apps/examples/documents + +# Build core packages when needed +pnpm build + +# Run tests +pnpm test + +# Format code +pnpm format +``` + +This workflow enables you to modify templates and see changes instantly in your browser, providing a smooth development experience similar to modern web frameworks. + ## Components htmldocs comes with a standard set of components to help you layout and style your documents. @@ -99,6 +172,68 @@ htmldocs also uses the [Paged.js library](https://pagedjs.org/) under the hood. |--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | Next.js | TypeScript | Turborepo | pnpm | +## Monorepo Architecture + +This project uses a monorepo structure with pnpm workspaces and Turbo for efficient development: + +``` +├── packages/ +│ ├── htmldocs/ # Main CLI and Next.js app +│ ├── react/ # React components (@htmldocs/react) +│ ├── render/ # PDF rendering engine (@htmldocs/render) +│ ├── eslint-config/ # Shared ESLint configuration +│ └── typescript-config/ # Shared TypeScript configuration +├── apps/ +│ ├── examples/ # Example templates and documents +│ └── docs/ # Documentation site +``` + +### Package Dependencies + +- `htmldocs` → depends on `@htmldocs/render` +- `examples` → depends on `htmldocs`, `@htmldocs/react`, `@htmldocs/render` +- All packages → share `@htmldocs/eslint-config` and `@htmldocs/typescript-config` + +The monorepo uses `workspace:*` protocol for internal dependencies, enabling seamless development across packages with automatic linking. + +## Contributing + +We welcome contributions! Here's how to get started: + +### Development Environment + +1. **Clone and setup**: + ```bash + git clone https://github.com/htmldocs-js/htmldocs.git + cd htmldocs + pnpm install + ``` + +2. **Start development**: + ```bash + ./dev.sh + ``` + +3. **Make changes** to templates in `apps/examples/documents/templates/` + +4. **See changes instantly** in your browser with hot reload + +### Common Tasks + +- **Add new templates**: Create `.tsx` files in `apps/examples/documents/templates/` +- **Modify components**: Edit `packages/react/components/` (requires `pnpm build`) +- **Update CLI**: Edit `packages/htmldocs/src/cli/` (restart dev server) +- **Fix rendering**: Edit `packages/render/src/` (requires `pnpm build`) + +### Testing + +```bash +pnpm test # Run all tests +pnpm test:coverage # Run tests with coverage +pnpm lint # Check code style +pnpm format # Format code +``` + ## License MIT License diff --git a/apps/examples/documents/templates/Invoice.tsx b/apps/examples/documents/templates/Invoice.tsx index 21e2b6c..315e2d2 100644 --- a/apps/examples/documents/templates/Invoice.tsx +++ b/apps/examples/documents/templates/Invoice.tsx @@ -84,7 +84,7 @@ function Invoice({ billedTo, yourCompany, services }: InvoiceProps) { className="flex flex-row items-center justify-between" >
#AB2324-01
Single File Mode
++ This is your Index.tsx file. Edit this file to see changes in real-time! +
+ +📝 Note: This application now only monitors changes to this Index.tsx file. + All other UI elements have been simplified for a clean, focused experience.
++ Try editing this file to see the hot reload in action! The changes will appear + instantly without any need to refresh the page. +
+