mirror of
https://github.com/penpot/penpot.git
synced 2026-03-31 05:31:07 -04:00
71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
# Penpot Common – Agent Instructions
|
||
|
||
A shared module with code written in Clojure, ClojureScript, and
|
||
JavaScript. Contains multiplatform code that can be used and executed
|
||
from the frontend, backend, or exporter modules. It uses Clojure reader
|
||
conditionals to specify platform-specific implementations.
|
||
|
||
## General Guidelines
|
||
|
||
To ensure consistency across the Penpot stack, all contributions must adhere to
|
||
these criteria:
|
||
|
||
### 1. Testing & Validation
|
||
|
||
If code is added or modified in `src/`, corresponding tests in
|
||
`test/common_tests/` must be added or updated.
|
||
|
||
* **Environment:** Tests should run in both JS (Node.js) and JVM environments.
|
||
* **Location:** Place tests in the `test/common_tests/` directory, following the
|
||
namespace structure of the source code (e.g., `app.common.colors` ->
|
||
`common-tests.colors-test`).
|
||
* **Execution:** Tests should be executed on both JS (Node.js) and JVM environments:
|
||
* **Isolated:**
|
||
* JS: To run a focused ClojureScript unit test: edit the
|
||
`test/common_tests/runner.cljs` to narrow the test suite, then
|
||
`pnpm run test:js`.
|
||
* JVM: `pnpm run test:jvm --focus common-tests.my-ns-test`
|
||
* **Regression:**
|
||
* JS: Run `pnpm run test:js` without modifications on the runner (preferred)
|
||
* JVM: Run `pnpm run test:jvm`
|
||
|
||
### 2. Code Quality & Formatting
|
||
|
||
* **Linting:** All code changes must pass linter checks:
|
||
* Run `pnpm run lint:clj` for CLJ/CLJS/CLJC
|
||
* **Formatting:** All code changes must pass the formatting check
|
||
* Run `pnpm run check-fmt:clj` for CLJ/CLJS/CLJC
|
||
* Run `pnpm run check-fmt:js` for JS
|
||
* Use `pnpm run fmt` to fix all formatting issues (`pnpm run
|
||
fmt:clj` or `pnpm run fmt:js` for isolated formatting fix).
|
||
|
||
## Code Conventions
|
||
|
||
### Namespace Overview
|
||
|
||
The source is located under `src` directory and this is a general overview of
|
||
namespaces structure:
|
||
|
||
- `app.common.types.*` – Shared data types for shapes, files, pages using Malli schemas
|
||
- `app.common.schema` – Malli abstraction layer, exposes the most used functions from malli
|
||
- `app.common.geom.*` – Geometry and shape transformation helpers
|
||
- `app.common.data` – Generic helpers used across the entire application
|
||
- `app.common.math` – Generic math helpers used across the entire application
|
||
- `app.common.json` – Generic JSON encoding/decoding helpers
|
||
- `app.common.data.macros` – Performance macros used everywhere
|
||
|
||
|
||
### Reader Conditionals
|
||
|
||
We use reader conditionals to differentiate implementations depending on the
|
||
target platform where the code runs:
|
||
|
||
```clojure
|
||
#?(:clj (import java.util.UUID)
|
||
:cljs (:require [cljs.core :as core]))
|
||
```
|
||
|
||
Both frontend and backend depend on `common` as a local library (`penpot/common
|
||
{:local/root "../common"}`).
|
||
|