@joeblew999/remy-ui

The UI every Remy app shares: stock shadcn components and theme, fonts, Paraglide catalogs and locale helpers, the site and app pages, TanStack Start glue, and the Playwright checks that prove them. Consumers are remy-auth (server-rendered) and remy-auth-app (prerendered); both run the same checks.

shadcn, stockCopy Anchor Link

Everything in src/components, src/hooks and src/styles/globals.css is what the pinned shadcn CLI writes (monorepo layout: the app's components.json routes shadcn add here), including cn from shadcn's own cn package; nothing there is edited by hand. npm run ui:components and npm run ui:theme regenerate them and npm run ui:verify fails on any drift (see docs/gui.md). Blocks are owned copies in src/blocks.

UsageCopy Anchor Link

Import the package's stylesheet in the app's CSS (here src/styles.css), then tell Tailwind where the app's own classes live. tailwind.css imports globals.css, fonts.css and text.css in that order and declares the package's own @source:

@import "@joeblew999/remy-ui/tailwind.css";
@source "../src";

fonts.css names fontaine's fallback faces; add FontaineTransform.vite({ fallbacks: { 'Geist Variable': ['Arial'] } }) before Tailwind in the Vite config (remy-auth's vite.config.ts is the example).

Every page is one of two kinds, never mixed (paths' isAppPath is the rule; each app lists its own):

• Site pages (the app's sitePaths), framed by SiteShell: complete without JavaScript, indexed, in the sitemap, judged by Lighthouse and Core Web Vitals.
• App pages (its appPaths, under /app), framed by AppShell (shadcn's sidebar-16 block): they need JavaScript and pageHead marks them noindex. AppShell has its own export so a site page never downloads it.
• App navigation: the app's own list, in its defineRemyApp config (app-config).

remy-auth's own pages (the home and formats pages, the app's formats, clock, demo, location, settings and account pages, their navigation lists, the demo reservation and their checks) are not the platform's: they are @joeblew999/remy-showcase (packages/showcase, its README), for the apps that show them. Tablets and desktops get the sidebar (collapsing to icons); phones get the bottom bar (blocks/bottom-nav, stock shadcn parts, since shadcn has no bottom navigation) with the core pages and More, which opens the sidebar. Why: the plan.

What every app on the package has, so the shared tasks and checks work in it (remy-auth-app is the prerendered example):

• Its frame settings, once, in defineRemyApp (app-config): its name (the product's, written once), source, the site header's and the app sidebar's links (each written with TanStack's linkOptions, so it is checked against the app's own routes where it is written). The shared frame names no route but /, so an app with other pages than remy-auth's type-checks as it is.
• Its root renders pages in AppProviders (providers), with that config and the root loader's preferred language: reading direction, the theme (the header's toggle and the Settings page need it), the frame settings and the language to offer, which every frame reads, so no page passes it. The shared themeChecks fail without it.
• A route for every path in appPaths and sitePaths, each a few lines over the shared page (the showcase's Clock spreads clockRouteOptions from @joeblew999/remy-showcase/clock-route).
• tests/smoke.spec.ts, one smokeChecks(...) call: npm run test -- smoke and the live smoke after every deploy run it, and fail with "No tests found" without it.
• .plans/now.md, the one ordered list of open work (remy plans check, in the check).
• Installs and upgrades through the package's commands, never by hand: npm run setup (install, skills, MCP, the installation's checks) and npm run upgrade -- <version> (the exact package version and the CI workflow at the same tag, then the same checks). Both take GitHub Packages' token from gh auth token.

ExportsCopy Anchor Link

All under @joeblew999/remy-ui/, as TSX and CSS for Vite and Tailwind consumers.

The package's dependencies are the platform's one dependency set, pinned exactly: the framework (React, TanStack Start, Router and Query), the toolchain (Vite, Wrangler, Tailwind, TypeScript) and the tools the shared tasks and checks run (Playwright, Lighthouse, the DevTools MCP server, npm-check-updates). An app names only the package; remy.singleCopy in its package.json lists those that break when installed twice, which the check's single-copies part keeps (the command line).

LanguageCopy Anchor Link

Language behaviour is Paraglide's: strategies url, cookie, custom-chinese (Paraglide's own custom-strategy hook, in matching.js), preferredLanguage, baseLocale, every locale prefixed in the URL, configured once in paraglide.mjs, which compiles messages/*.json during type generation and the Vite build. Pass { locale } explicitly to every message call; there is no process-wide locale. A server-rendered app runs the middleware and passes the visitor's preference down; a prerendered app resolves it in the browser after hydration; both render the same components. The languages are the locales in project.inlang/settings.json; every catalog except English and Spanish (Arabic, Persian, Hebrew, Thai, Japanese, Traditional Chinese, Hindi, Amharic, Polish, Turkish and German) is agent-authored and unreviewed.

PublishingCopy Anchor Link

The package is @joeblew999/remy-ui on GitHub Packages (the scope must equal the GitHub owner there). npm run dev:release (alias release) does the whole release from this machine, stopping at the first failure: translations complete and current (remy i18n check, strict), every check of ours (remy verify), shadcn's files exactly as its CLI writes them (npm run ui:verify), Google's Lighthouse audits, and Core Web Vitals measured cold on a throwaway Cloudflare Worker (npm run test -- cwv: the first visits after a deploy, which is what a slow page costs most). Then it tags vX.Y.Z from packages/ui/package.json, pushes, publishes with your gh token and creates the GitHub release from the matching CHANGELOG section. CI (.github/workflows/google.yml) repeats level 2 on the tag.

Before releasing, one commit: the version in packages/ui/package.json (and in packages/contract/package.json when the contract changed) and the CHANGELOG section. No other file names a version: the workspaces depend on each other with "*" and the contract's peer range is open-ended. The task refuses a dirty tree, a branch other than main, or an existing tag.

Consumers add to their .npmrc:

@joeblew999:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

and install through npm run setup, which takes a read:packages token from gh auth token (or GITHUB_TOKEN in the shell). Released versions are in the changelog.

Writing a partCopy Anchor Link

A part is a feature an app switches on or off with one line in its src/parts.json. The platform's parts are listed by name ("seo-routes"); any package can offer parts too, listed as "<package>/<name>" ("@joeblew999/remy-showcase/time-zones"), and they work the same way.

1. Folder: src/parts/<name>/ in the package, with any of:
   • routes/: TanStack route files, mounted beside the app's own src/routes when the part is listed;
   • entry modules (e.g. ui.tsx, place.ts) the app imports as virtual:remy-parts/<name>/<entry>: the real exports when listed, undefined when not, so the app writes {Card && <Card />} or getPlace?.() and nothing ships when the part is off. One module per entry keeps code splitting;
   • checks.js, whose default export (options, listed) => void runs its Playwright checks: partChecks() runs it only when the part is listed, with the app's options[<name>].
2. Catalog: the platform's are catalog in src/parts/list.js; another package's are its src/parts/catalog.json, exported as <package>/parts/catalog.json, in the same shape: routes, requires (parts that must be listed too), entries (entry → export names), app (options the app supplies from its own src/parts/<name>.ts, read as virtual:remy-parts/<name>/app) and sitePaths (site pages it adds, for the sitemap and its checks).
3. Types: declare its virtual modules in the package's src/parts/virtual.d.ts (another package's references the platform's with /// <reference types="@joeblew999/remy-ui/parts/virtual" />). A part links only to its own routes, or to the app's pages through its app options (the time-zones part's breadcrumb takes parent), never to a page another app may not have: the consumer fixture lists a showcase part and type-checks it without the showcase's pages.
4. Prove it: npm run dev:change passes with the part listed, with it removed, and with the list empty (run a build once after editing src/parts.json, which regenerates the route tree).

What stays a plain package module instead: code every app needs (observability), a hook an app must always call (leave-guard), or a shared page's own controls (search-params).