From 0b5fa027e60c4f77385f4f7ebeded3899ed87e05 Mon Sep 17 00:00:00 2001
From: Kyohei Fukuda <kyoheif@wix.com>
Date: Tue, 4 Mar 2025 14:16:16 +0900
Subject: [PATCH] Add .clinerules file to outline project overview and
 development guidelines

---
 .clinerules | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 .clinerules

diff --git a/.clinerules b/.clinerules
new file mode 100644
index 00000000..f393b64d
--- /dev/null
+++ b/.clinerules
@@ -0,0 +1,52 @@
+# .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.
+