You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/ARCHITECTURE.md
+15-22Lines changed: 15 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,10 @@
5
5
This is a modern implementation of the PIE (Platform Independent Elements) specification, built with TypeScript, ESM, and contemporary tooling. The project currently syncs React-based elements from the upstream [pie-elements](https://github.com/PieLabs/pie-elements) repository while providing modern ESM packaging, Vite builds, and improved developer experience.
6
6
7
7
**Current Status**: Early development (v0.1.0)
8
+
8
9
- 28 React elements synced from upstream
9
10
- Core infrastructure and build tooling established
10
-
-Elements are private packages (not yet published to npm)
11
+
-Element and lib packages are publish-enabled (versioned/released via Changesets + GitHub Actions)
11
12
- Future plans include native Svelte 5 implementations and public npm releases
12
13
13
14
## Core Philosophy
@@ -434,20 +435,14 @@ $ git push
434
435
435
436
**Publishing strategy:**
436
437
437
-
**Current Status**: All packages are currently marked as `"private": true` and are not published to npm. This is an early development phase decision.
438
-
439
-
**Future Publishing Plan**:
438
+
**Current Status**: `@pie-element/*` and `@pie-lib/*` packages are configured to be publishable and are managed by the Changesets release workflow.
440
439
441
-
Once the project reaches a stable release (v1.0.0+):
440
+
**Release behavior**:
442
441
443
-
-**Element packages** (`@pie-element/*`) - Will be published for external consumption
444
-
-**Library packages** (`@pie-lib/*`) - Will **NOT** be published independently
445
-
- These are internal implementation details of the elements
446
-
- Bundled into element packages during build
447
-
- External consumers will never import `@pie-lib` packages directly
448
-
- Simplifies the public API surface
442
+
-**Element packages** (`@pie-element/*`) are versioned and published by CI.
443
+
-**Library packages** (`@pie-lib/*`) are also versioned/publishable so internal dependency graphs stay coherent during coordinated releases.
449
444
450
-
This will differ from the legacy approach where `@pie-lib`packages were independently published and consumed. In pie-elements-ng, `@pie-lib` packages exist purely for internal code organization within the monorepo.
445
+
This differs from earlier phases where most synced packages were intentionally private.
451
446
452
447
**Trade-offs:**
453
448
@@ -581,7 +576,7 @@ The architecture consists of three main layers:
581
576
**Key organizational decisions**:
582
577
583
578
-**@pie-lib integration**: The `@pie-lib/*` packages (formerly a separate repository) are now in `packages/lib-react/` for better version management and coordination
584
-
-**Versioning**: Independent versioning using Changesets. Most synced packages are marked private; core packages like `@pie-element/core` are publishable
579
+
-**Versioning**: Changesets-managed coordinated versioning and publishing for `@pie-element/*` and `@pie-lib/*` packages
585
580
-**Workspaces**: Bun workspaces with `"workspace:*"` references ensure consistency across the monorepo
586
581
587
582
### Element Package Anatomy
@@ -1170,12 +1165,10 @@ Note: `'unsafe-inline'` for styles is required for Svelte scoped styles.
1170
1165
1171
1166
### NPM Publishing
1172
1167
1173
-
**Current Status**: Packages are not yet published to npm (all marked as `"private": true`).
1174
-
1175
-
**Future Publishing Strategy**: Once ready for public release, packages will be published via GitHub Actions:
1168
+
**Current Strategy**: Publishing is CI-driven via GitHub Actions and Changesets:
1176
1169
1177
1170
1. Developer creates changeset: `bun run changeset`
1178
-
2. PR merged to main
1171
+
2. PR merged to `master`
1179
1172
3. GitHub Action creates "Version Packages" PR
1180
1173
4. Maintainer merges Version PR
1181
1174
5. Packages automatically published to npm
@@ -1190,7 +1183,7 @@ See [PUBLISHING.md](./PUBLISHING.md) for details (when available).
1190
1183
1191
1184
This project is designed to use **workspace-wide versioning** where all packages share the same version number. This is a deliberate architectural decision that differs from the upstream pie-elements/pie-lib projects.
1192
1185
1193
-
**Current Status**: All packages are at version `0.1.0` and marked as `"private": true` (not published). Workspace-wide versioning will be enforced when packages are published publicly.
1186
+
**Current Status**: `@pie-element/*` and `@pie-lib/*` packages are publish-enabled and released through the Changesets CI flow.
1194
1187
1195
1188
See [section 8 above](#8-workspace-wide-versioning) for a detailed explanation of why this approach was chosen and the problems it solves.
1196
1189
@@ -1222,12 +1215,12 @@ $ bun run changeset
1222
1215
@pie-element/multiple-choice: 1.5.0 # Will be published to npm
1223
1216
@pie-element/drag-in-the-blank: 1.5.0 # Will be published to npm (even though unchanged)
1224
1217
1225
-
#Internal packages are versioned but NOT published:
1226
-
@pie-lib/render-ui: 1.5.0# Internal only (bundled into elements)
1227
-
@pie-lib/math-rendering: 1.5.0# Internal only (bundled into elements)
1218
+
#Lib packages are versioned in the same coordinated release:
1219
+
@pie-lib/render-ui: 1.5.0
1220
+
@pie-lib/math-rendering: 1.5.0
1228
1221
```
1229
1222
1230
-
**Current Reality**: All packages are at `0.1.0` and private (not published).
1223
+
**Current Reality**: Package releases are coordinated through the CI release workflow.
1231
1224
1232
1225
This ensures all packages are always compatible and tested together. External consumers only interact with `@pie-element/*` packages, which bundle all necessary dependencies.
0 commit comments