Contributing to plocks
How the repo is laid out, how to run it locally, and what it takes to land a component, a demo, or a docs page.
plocks is developed in the open at platform-blocks/plocks. Issues and pull requests are welcome — this page is the short version of CONTRIBUTING.md, which ships with the repo.
Repo layout
packages/uiThe core library published as@plocks/ui— 100+ components, hooks, and the theming systempackages/chartsThe charting package published as@plocks/charts— 24 chart types on that same themingpackages/{dates,code,media,carousel,spotlight}The packages built on@plocks/ui: date pickers, code and Markdown, audio and video, the carousel, and Spotlightapps/docsThis documentation site (Expo Router, statically rendered web)scripts/Generators: demos, docs metadata, llms.txt, sitemap, exports map, release
Set up the repo
plocks is one npm workspace. Install from the root — the workspaces are linked, so the docs site runs against your local packages rather than the published ones.
git clone https://github.com/platform-blocks/plocks.git
cd plocks
npm installStart the docs site. It is the main development surface: every component demo renders there, against the source you are editing.
npm run devPress
w for web, or open the project in Expo Go, an iOS simulator, or an Android emulator.Working on the UI package
Each component lives in
packages/<package>/src/components/<Name>/ — most in packages/ui — with a conventional shape: tests, docs metadata, and demos beside the source:Button/
Button.tsx types.ts index.ts
__tests__/ # jest tests
meta/component.md # frontmatter: title, category, tags + prose
demos/<slug>/ # index.tsx (default-export Demo) + description.mdBuild, test, and lint the package from the repo root:
npm run ui:build # rollup + type declarations
npm run ui:test # jest (70% coverage threshold)
npm run ui:lint # eslintAdding a component
A new component is five steps, and the last one writes most of the docs for you:
1.
Create the directory following the shape above.
2.
Export it from its package's
src/index.ts.3.
In
packages/ui, run npm run ui:exports to regenerate the per-component exports map in package.json — CI fails if it is stale.4.
Add a row to
apps/docs/config/coreComponents.ts.5.
Run
npm run docs:all — the docs route, nav entry, props table, demo code blocks, and llms.txt page are all generated.Adding a demo
Demos are the examples on a component page, and each one is a real component the site renders. Create
demos/<slug>/index.tsx with a default-exported Demo, plus a description.md carrying title, order, and tags frontmatter, then regenerate:npm run demos:allThe validator that runs afterwards fails on a missing description, a duplicate slug, or a demo that does not compile.
Working on the docs site
Guide pages keep their copy in JSX-free modules under
apps/docs/config/ — gettingStarted.ts, templates.ts, faq.ts, and this page's contribute.ts — so scripts/generate-llms.ts can render the same source into llms.txt for language models. A new page touches four files:•
the route file under
app/,•
a config module holding its copy,
•
config/navigationConfig.ts for the sidebar entry,•
config/routeSeo.ts for the title and description — the prerender check fails without them.Before opening a pull request that changes docs content, regenerate the derived files:
npm run docs:allVerifying a change
One command covers both packages — the exports map, the skills check, lint, and the test suites:
npm run verify:packagesStarter templates & community
The starter templates are separate repositories, listed on the site from one config module.
•
Templates live under the platform-blocks GitHub org and are listed via
apps/docs/config/templates.ts.•
Built a starter with your own stack? Share it with us — accepted templates get listed on the Getting Started page.
Releases
Maintainers run
npm run release, which verifies every package (exports, lint, tests, build) and publishes them to npm together, at one version. Contributors never need to bump a version — say what the change is in the pull request and it lands in the next release.Stuck on any of this? Open a discussion or issue — a question that needed asking is usually a docs bug worth fixing.
React Native design for iOS, Android, and Web.
Quick Links
Resources