|
| 1 | +# Shadcn Parity |
| 2 | + |
| 3 | +## Core Contract |
| 4 | + |
| 5 | +When the user asks for shadcn parity, treat `../shadcn` as the source of |
| 6 | +truth for registry behavior and patterns. |
| 7 | + |
| 8 | +Do not give them "inspired by shadcn". Do not invent a Plate-specific model |
| 9 | +when upstream shadcn already has one. |
| 10 | + |
| 11 | +The rule is simple: |
| 12 | + |
| 13 | +- upstream schema first |
| 14 | +- upstream resolver behavior first |
| 15 | +- upstream file/layout patterns first |
| 16 | +- upstream namespace semantics first |
| 17 | +- Plate divergence only when the repo has a real constraint |
| 18 | + |
| 19 | +Plate does **not** fork shadcn CLI. Do not talk about Plate as if it owns a |
| 20 | +custom installer. Plate owns a registry and template sync layer around the |
| 21 | +upstream shadcn contract. |
| 22 | + |
| 23 | +If you diverge, say exactly why. |
| 24 | + |
| 25 | +## Ownership |
| 26 | + |
| 27 | +Shadcn owns the contract: |
| 28 | + |
| 29 | +- registry item schema |
| 30 | +- namespace semantics like `@shadcn/button` and other registry prefixes |
| 31 | +- resolver behavior for plain items, namespaced items, URLs, and local files |
| 32 | +- local-file add behavior |
| 33 | +- `components.json` registry semantics |
| 34 | + |
| 35 | +Plate owns the content and delivery: |
| 36 | + |
| 37 | +- registry source files under `apps/www/src/registry/*` |
| 38 | +- registry build logic in `apps/www/scripts/build-registry.mts` |
| 39 | +- generated registry output under `apps/www/public/r` and `apps/www/public/rd` |
| 40 | +- the `@plate` namespace configured in template `components.json` |
| 41 | +- template sync tooling in: |
| 42 | + - `tooling/scripts/update-template.sh` |
| 43 | + - `tooling/scripts/prepare-local-template-registry.mjs` |
| 44 | + |
| 45 | +Important boundary: |
| 46 | + |
| 47 | +- shadcn owns how registry items are resolved and installed |
| 48 | +- Plate owns what the registry contains and how local template sync feeds it |
| 49 | + |
| 50 | +Plate's registry build is custom. The goal is still upstream parity at the |
| 51 | +item and resolver boundary. |
| 52 | + |
| 53 | +## Registry Rules |
| 54 | + |
| 55 | +Registry items should stay as close as possible to upstream `RegistryItem` |
| 56 | +shape. |
| 57 | + |
| 58 | +When building or changing Plate registry items: |
| 59 | + |
| 60 | +- check `../shadcn` first |
| 61 | +- copy upstream file/layout/helper patterns when they fit |
| 62 | +- prefer upstream naming and dependency structure over Plate-specific novelty |
| 63 | +- keep dynamic Plate-specific behavior in build or sync tooling, not in a fake |
| 64 | + registry data model |
| 65 | + |
| 66 | +Registry dependency rules: |
| 67 | + |
| 68 | +- prefer `@shadcn/*` when an upstream shadcn item exists |
| 69 | +- prefer upstream namespace syntax over raw URLs when the namespace already |
| 70 | + covers the case |
| 71 | +- if upstream does not expose a small standalone item, use a small Plate |
| 72 | + registry item instead of dragging in a huge upstream dependency just to steal |
| 73 | + one internal file |
| 74 | +- do not expand compatibility hacks into new conventions |
| 75 | + |
| 76 | +Do not fork shadcn CLI to compensate for Plate registry problems. Fix the |
| 77 | +registry data or the Plate sync tooling instead. |
| 78 | + |
| 79 | +## Template Rules |
| 80 | + |
| 81 | +For template installs, shadcn CLI is still the installer. Plate supplies the |
| 82 | +registry. |
| 83 | + |
| 84 | +Template rules: |
| 85 | + |
| 86 | +- keep `templates/*/components.json` aligned with shadcn registry semantics |
| 87 | +- treat `@plate` in `components.json` as the install entrypoint for Plate |
| 88 | + items |
| 89 | +- prefer registry fixes over template-only patches when generated output is |
| 90 | + wrong |
| 91 | +- compare Plate output against `../shadcn` before inventing a custom rule |
| 92 | + |
| 93 | +For local template sync: |
| 94 | + |
| 95 | +- `--local` uses local-file mode, not localhost |
| 96 | +- local sync works by preparing a JSON mirror from `apps/www/public/rd` |
| 97 | +- local sync exists to feed upstream shadcn local-file install flow, not to |
| 98 | + replace it |
| 99 | + |
| 100 | +If a change would make public installs cleaner but would break local-file sync, |
| 101 | +call that out and fix both sides together. |
| 102 | + |
| 103 | +## Current Divergences |
| 104 | + |
| 105 | +These are real Plate divergences today. Treat them as constraints, not as a |
| 106 | +pattern to spread. |
| 107 | + |
| 108 | +- Plate publishes a registry from `apps/www`, not from upstream shadcn |
| 109 | + infrastructure |
| 110 | +- local template sync uses prepared JSON mirrors and local-file mode |
| 111 | +- template install entrypoints use the `@plate` registry in `components.json` |
| 112 | +- some built registry output may still emit absolute Plate self-URLs for |
| 113 | + compatibility; treat that as behavior to minimize, not a new model to copy |
| 114 | + |
| 115 | +## Red Flags |
| 116 | + |
| 117 | +Stop and reassess if you are about to do any of this: |
| 118 | + |
| 119 | +- describe Plate as a fork of shadcn CLI |
| 120 | +- invent a new Plate-only registry schema |
| 121 | +- replace upstream namespace behavior with raw URL sprawl |
| 122 | +- solve a registry issue by adding more installer logic when the data is wrong |
| 123 | +- patch templates by hand without checking whether the registry source is the |
| 124 | + real problem |
0 commit comments