# .clinerules

## Project Overview
- This repository hosts the pdfme libraries, which are distributed under multiple npm packages and developed in TypeScript.
- The libraries must function in both browser and Node.js environments.
- The core libraries rely on a forked version of [pdf-lib](https://pdf-lib.js.org/) (@pdfme/pdf-lib) to handle PDF rendering, including CJK font and SVG support.
- Official documentation references http://pdfme.com/
- The codebase includes:
  - **packages** directory: Contains the main libraries classified as:
    1. **@pdfme/generator, @pdfme/schemas, @pdfme/ui** – Tools for generating PDFs from JSON templates and designing templates/UI.
    2. **@pdfme/manipulator, @pdfme/converter** – Utilities for PDF manipulation (merge, split, convert to images, etc.).
    3. **@pdfme/common** – Common logic and shared types.
  - **website** directory: Docusaurus-based site at https://pdfme.com/ for official docs.
  - **playground** directory: React SPA for e2e tests, demos, and development checks.

## Development Guidelines

1. **Minimize Maintenance Overhead**
   - Avoid adding new dependencies unless strictly necessary. Provide a strong justification if a dependency is added.
   - Write as little code as possible. Remove or unify code that is not essential.
   - Shared functionality across packages should be relocated to **@pdfme/common**.
   - Only add tests that are truly needed for coverage. Avoid redundant or trivial tests.

2. **Functions and Interfaces**
   - Prefer pure functions without side effects for ease of unit testing.
   - Keep functions minimal, focusing on clarity and testability.
   - Any public function or interface modifications must be reflected in the documentation (under `website/docs`).

3. **Browser and Node.js Support**
   - Ensure all libraries work seamlessly in both the browser and Node.js.

4. **Code Formatting**
   - Do not include unnecessary formatting changes in commits.
   - Use `npm run prettier` at the root level as the project’s definitive formatting tool.

5. **Build and Test Requirements**
   - Pass `npm run build` and `npm run test` at the root level before merging changes.
   - Ensure no introduced changes break existing functionality in any package.

6. **Documentation Consistency**
   - When modifying or publishing any public API, confirm there is no conflict with existing docs in `website/docs`.
   - Update the documentation as needed to reflect interface changes.

7. **Minimal Scope Changes**
   - Keep PRs and commits scoped to the smallest functional update. 
   - Refrain from adding extraneous code or merging unrelated changes.

## Security and Maintenance
- Focus on secure implementation since many users will view and utilize this code.
- Always protect sensitive files (e.g., .env, credentials).
- Follow best practices in code organization, architecture, and testing.

