Skip to content

Open-source status page, incident response and uptime monitoring

chore: blog component registry (#1841)

Maximilian Kaskee34126a1484d
diff --git a/apps/web/public/assets/posts/shadcn-component-registry/shadcn-component-registry.png b/apps/web/public/assets/posts/shadcn-component-registry/shadcn-component-registry.png
new file mode 100644
index 000000000..4c95e75fa
Binary files /dev/null and b/apps/web/public/assets/posts/shadcn-component-registry/shadcn-component-registry.png differ
diff --git a/apps/web/src/app/api/search/route.ts b/apps/web/src/app/api/search/route.ts
index bee440296..ab065bba5 100644
--- a/apps/web/src/app/api/search/route.ts
+++ b/apps/web/src/app/api/search/route.ts
@@ -71,6 +71,7 @@ function search(params: SearchParams) {
...getPages("compare"),
...getPages("product"),
...getPages("guides"),
+ ...getPages("unrelated"),
home,
];
} else {
diff --git a/apps/web/src/content/pages/blog/shadcn-component-registry.mdx b/apps/web/src/content/pages/blog/shadcn-component-registry.mdx
new file mode 100644
index 000000000..a36923417
--- /dev/null
+++ b/apps/web/src/content/pages/blog/shadcn-component-registry.mdx
@@ -0,0 +1,296 @@
+---
+title: "How We Built Our shadcn Component Registry"
+description: "From duplicated components across three apps to a clean registry - our journey to building a shadcn/ui - compatible component library."
+author: "Maximilian Kaske"
+publishedAt: "2026-02-15"
+image: "/assets/posts/shadcn-component-registry/shadcn-component-registry.png"
+category: "engineering"
+---
+
+After splitting our main web project into three distinct apps - `dashboard`, `status-page`, and `web` (our marketing site) - we'd duplicated the [shadcn/ui](https://ui.shadcn.com) components across each of them. Quick and easy, but not sustainable. It was time to consolidate our UI components into `packages/ui`.
+
+**The advantage:** maintain components in one place.
+
+**The disadvantage:** every change needs validation across all three apps (especially CSS).
+
+While refactoring our component library, I realized we could take this further: what if we turned our custom "blocks" into proper shadcn registry components and distributed them via the shadcn CLI? Better yet, what if we could use the shadcn CLI itself to add and update components within our `packages/ui`?
+
+The challenge: we wanted to use the exact same components in our codebase - no build steps, no bundler, no webpack configuration - while making them easily distributable through shadcn's standard conventions.
+
+Our monorepo structure looks like this:
+
+```
+openstatus/
+├── apps/
+│ ├── dashboard/ # Main dashboard app
+│ ├── status-page/ # Public status pages
+│ ├── web/ # Marketing site
+│ └── ...
+├── packages/
+│ ├── ui/ # Shared UI components
+│ │ ├── src/
+│ │ │ ├── components/
+│ │ │ │ ├── ui/ # shadcn components
+│ │ │ │ └── blocks/ # Custom blocks
+│ │ │ ├── lib/
+│ │ │ └── hooks/
+│ │ ├── components.json
+│ │ ├── registry.json
+│ │ └── package.json
+│ ├── db/
+│ ├── api/
+│ └── ...
+└── pnpm-workspace.yaml
+```
+
+## First Approach: Following the shadcn Defaults
+
+The most obvious approach: just follow shadcn's standard setup. Every shadcn project uses a `@/` alias, so why not do the same in `packages/ui`?
+
+Here's the thing - TypeScript won't complain about this setup within the package itself. Everything type-checks perfectly. The problem only surfaces when you actually try to use these components in your apps.
+
+The default shadcn approach uses a simple `@/` alias in `packages/ui/tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "paths": {
+ "@/*": ["./src/*"]
+ }
+ }
+}
+```
+
+And write components using this alias in `packages/ui/src/components/ui/button.tsx`:
+
+```tsx
+// ✅ The shadcn/ui way
+import { cn } from "@/lib/utils";
+import { Slot } from "@radix-ui/react-slot";
+
+export function Button({ className, ...props }) {
+ return <button className={cn("...", className)} {...props} />;
+}
+```
+
+The problem? When you import this button in your app:
+
+```tsx
+// apps/dashboard/src/app/page.tsx
+import { Button } from "@openstatus/ui/components/ui/button";
+// ❌ Error: Cannot find module '@/lib/utils'
+// The @/ alias doesn't exist in the app's context!
+```
+
+## Second Approach: Bundle It Up
+
+If the imports are the problem, what if we bundle the package and distribute compiled output? Tools like tsup can handle this cleanly, and many modern component libraries go this route.
+
+Here's what this would look like with tsup:
+
+```ts
+// packages/ui/tsup.config.ts
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+ entry: ["src/index.ts"],
+ format: ["cjs", "esm"],
+ dts: true,
+ sourcemap: true,
+ external: ["react", "react-dom"],
+ banner: {
+ js: '"use client";',
+ },
+});
+```
+
+And adding the build step to the package:
+
+```json
+// packages/ui/package.json
+{
+ "scripts": {
+ "build": "tsup",
+ "dev": "tsup --watch"
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+}
+```
+
+The downsides:
+- Every change requires a rebuild (yes, even with `--watch` mode, there's still a delay)
+- Adds complexity to the development workflow
+- Build output needs to be managed and debugged
+- Still doesn't help with shadcn CLI integration for the registry
+
+## Third Approach: Configure Webpack
+
+What about webpack aliases? Next.js lets you customize the webpack config, so theoretically you could tell it how to resolve the imports. Here's what a working config would look like:
+
+```js
+// apps/dashboard/next.config.js
+const path = require("path");
+
+const nextConfig = {
+ webpack: (config) => {
+ config.resolve.alias = {
+ ...config.resolve.alias,
+ // Resolve @openstatus/ui to source
+ "@openstatus/ui": path.resolve(__dirname, "../../packages/ui/src"),
+ // ALSO resolve @/ to the ui package - this is critical!
+ "@": path.resolve(__dirname, "../../packages/ui/src"),
+ };
+ return config;
+ },
+ transpilePackages: ["@openstatus/ui"],
+};
+```
+
+The issue? You need **both** aliases. Just pointing `@openstatus/ui` to the source isn't enough - you also need to tell the app how to resolve the `@/` imports that appear _inside_ the package's components.
+
+But now you have a **new problem**: what if your app also wants to use `@/` for its own imports? You've just created a conflict! The `@/` alias now points to the UI package, not your app's source directory. You'd need to choose between:
+
+1. Never using `@/` in your app (use a different alias like `@app/`)
+2. Using a different alias in the UI package (but then it's not compatible with standard shadcn components)
+3. Some complex webpack resolver that checks the importing file's location to decide what `@/` means (maintainability nightmare)
+
+The problems:
+- Fragile configuration that breaks with Next.js updates
+- Needs to be duplicated in every app
+- Turbopack doesn't support custom webpack configs
+- **Most importantly:** Creates alias conflicts between app and package
+- Forces you to abandon standard `@/` convention in either the app or package
+
+## Fourth Approach: The Elegant Solution
+
+After three dead ends, we stepped back and thought differently. What if we stopped fighting against the monorepo structure and embraced it instead?
+
+The insight: `@openstatus/ui` is already a valid import in every app - it's right there in their `package.json`. What if we used that same alias **within** `packages/ui` itself?
+
+This means components would import from each other using `@openstatus/ui/...` internally. Then, when building the registry for distribution, we simply replace `@openstatus/ui` with `@`. That's it.
+
+No bundler. No webpack config. No alias conflicts. Just a clever use of TypeScript path mapping and a simple find-replace at build time.
+
+Here's the setup in `packages/ui/tsconfig.json`:
+
+```json
+{
+ "extends": "@openstatus/tsconfig/react-library.json",
+ "compilerOptions": {
+ "paths": {
+ "@openstatus/ui/*": ["./src/*"]
+ }
+ }
+}
+```
+
+And the key part in `packages/ui/components.json`:
+
+```json
+{
+ "aliases": {
+ "components": "@openstatus/ui/components",
+ "utils": "@openstatus/ui/lib/utils",
+ "ui": "@openstatus/ui/components/ui",
+ "lib": "@openstatus/ui/lib",
+ "hooks": "@openstatus/ui/hooks"
+ }
+}
+```
+
+### The Bonus: shadcn CLI Integration
+
+This setup unlocks a powerful benefit: **we can use the shadcn CLI directly in our package!**
+
+When shadcn releases new components or updates, we simply run:
+
+```bash
+cd packages/ui
+npx shadcn add button # Add new components
+npx shadcn diff button # Check for updates
+```
+
+The CLI reads our `components.json` and automatically uses the `@openstatus/ui` aliases. Newly added components work immediately in both the package and all consuming apps - no manual import rewrites, no configuration updates. It just works.
+
+### How It Looks in Practice
+
+Components within the package import from each other using `@openstatus/ui`:
+
+```tsx
+// packages/ui/src/components/blocks/status-banner.tsx
+import { Tabs, TabsContent } from "@openstatus/ui/components/ui/tabs";
+import { cn } from "@openstatus/ui/lib/utils";
+import type { StatusType } from "@openstatus/ui/components/blocks/status.types";
+```
+
+Apps import using the exact same pattern:
+
+```tsx
+// apps/dashboard/src/app/layout.tsx
+import { Toaster } from "@openstatus/ui/components/ui/sonner";
+import { cn } from "@openstatus/ui/lib/utils";
+```
+
+Notice something? **The imports are identical.** Whether you're inside the package or inside an app, the import path is the same. This consistency eliminates a whole class of path-resolution bugs.
+
+### The Magic: Import Transformation
+
+When building the registry for public distribution, we transform the imports with a simple regex (`packages/ui/scripts/transform-imports.mjs`):
+
+```js
+// Transform: @openstatus/ui/components/ui/button → @/components/ui/button
+content = content.replace(
+ /@openstatus\/ui\/(components|lib|hooks|types)/g,
+ "@/$1"
+);
+```
+
+This converts our package-specific imports into the standard shadcn `@/` convention that everyone expects.
+
+### Publishing the Registry
+
+The last piece of the puzzle is getting our components into a public registry that others can install. The build pipeline is a three-step process defined in `packages/ui/package.json`:
+
+```json
+{
+ "scripts": {
+ "registry:build": "node scripts/transform-imports.mjs && cd dist && shadcn build && cd .. && node scripts/copy-to-web.mjs"
+ }
+}
+```
+
+Here's what each step does:
+
+1. **Transform imports** (`transform-imports.mjs`): Copies source files to `dist/` and rewrites all `@openstatus/ui` imports to `@` for standard shadcn compatibility
+2. **Build registry** (`shadcn build`): Generates the registry JSON files that describe each component and its dependencies
+3. **Copy to web** (`copy-to-web.mjs`): Moves the generated registry files to our Next.js app's public directory for hosting
+
+The `copy-to-web.mjs` script is simple:
+
+```js
+const registryDir = join(ROOT_DIR, "dist/public/r");
+const targetDir = join(WEB_APP_PUBLIC_DIR, "r");
+cpSync(registryDir, targetDir, { recursive: true, force: true });
+```
+
+Now when users run:
+
+```bash
+npx shadcn@latest add https://openstatus.dev/r/status-banner.json
+```
+
+They're pulling from `apps/web/public/r/status-banner.json`, which was generated from the same components we use internally.
+
+## The Result
+
+What started as a refactoring task turned into a clean solution for both our internal needs and public distribution:
+
+- **One source of truth**: All three apps import from `@openstatus/ui`
+- **Zero build overhead**: Components work directly in development with no compilation
+- **Standard shadcn workflow**: `npx shadcn add/diff` works seamlessly in the package
+- **Public registry**: Anyone can install our components via the shadcn CLI
+
+The key insight was embracing the monorepo structure instead of fighting it. By using the package name as the import alias, we avoided all the pitfalls of other approaches: no bundler complexity, no webpack configuration fragility, and no alias conflicts.
+
+If you're running a multi-app monorepo with shared components, this pattern might save you considerable time and headaches. And if you need battle-tested status page components, check out our [component registry](/registry) - they're ready to drop into your project.
diff --git a/apps/web/src/content/pages/unrelated/registry.mdx b/apps/web/src/content/pages/unrelated/registry.mdx
index d3b1ed4d1..e57f86ee7 100644
--- a/apps/web/src/content/pages/unrelated/registry.mdx
+++ b/apps/web/src/content/pages/unrelated/registry.mdx
@@ -6,21 +6,21 @@ description: "Install beautiful, accessible React components for status pages. P
category: "Documentation"
---
-Build your status page in minutes, not hours. The Openstatus registry gives you production-ready React components specifically designed for status pages. Built on top of [shadcn/ui](https://ui.shadcn.com), these components are accessible, customizable, and battle-tested in production.
+Build your status page in minutes, not hours. The openstatus registry provides production-ready React components specifically designed for status pages. Built on top of [shadcn/ui](https://ui.shadcn.com), these components are accessible, customizable, and battle-tested in production.
## What is the Registry?
-The Openstatus registry is a shadcn/ui-compatible collection of pre-built components for common status page patterns. Instead of building status indicators, event timelines, and monitoring displays from scratch, you can install and customize these components directly into your project.
+The openstatus registry is a collection of shadcn/ui-compatible, pre-built components for common status page patterns. Instead of building status indicators, event timelines, and monitoring displays from scratch, install and customize these components directly into your project.
All components are:
- **Accessible** - Built with ARIA patterns and keyboard navigation
- **Customizable** - Fully themeable with Tailwind CSS
- **Type-safe** - Written in TypeScript with complete type definitions
-- **Production-ready** - Battle-tested in production at Openstatus
+- **Production-ready** - Battle-tested in production at openstatus
-## Complete Example
+## Example
-Hover the example below to learn which component is being used.
+Hover over the example below to see which component is being used.
<Grid cols={1}>
@@ -32,9 +32,9 @@ Hover the example below to learn which component is being used.
</Grid>
-> We are working on matching the component `Props` and the [`@openstatus/sdk-node`](https://jsr.io/@openstatus/sdk-node) return values, allowing you to use our SDK to build your own custom status page.
+> We are working on aligning component `Props` with [`@openstatus/sdk-node`](https://jsr.io/@openstatus/sdk-node) return values, enabling you to use our SDK to build your own custom status page.
-See the [complete example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) for full source code and usage patterns.
+View the [GitHub source code](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) for examples and usage patterns.
## Installation
@@ -44,18 +44,30 @@ Install any component with a single [shadcn CLI](https://ui.shadcn.com/docs/cli)
npx shadcn@latest add https://openstatus.dev/r/status-complete
```
+Or install the registry first:
+
+```bash
+pnpm dlx shadcn@latest registry add @openstatus
+```
+
+ And install the component via:
+
+```bash
+pnpm dlx shadcn@latest add @openstatus/status-complete
+```
+
### Available Components
-Components are organized by function:
+Components are organized by functionality:
- **Collections:** `status-complete`, `status-essentials` - Full status page bundles
- **Building Blocks:** `status-banner`, `status-bar`, `status-feed`, `status-events`, `status-component`, `status-icon`, `status-layout`, `status-timestamp` - Individual components
-Browse the full registry at [openstatus.dev/r/registry.json](https://openstatus.dev/r/registry.json)
+Explore the full registry at [openstatus.dev/r/registry.json](https://openstatus.dev/r/registry.json)
---
-Using openstatus but want a custom theme?
+Want to customize your theme?
<ButtonLink href="https://themes.openstatus.dev" children="Go to Themes Explorer" />
@@ -63,11 +75,11 @@ Using openstatus but want a custom theme?
## Learn More
-- [Complete Example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) - See all components in action
+- [Source Code Example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) - See all components in action
+- [Blog Post](/blog/shadcn-component-registry) - How We Build Our shadcn Component Registry
- [Openstatus SDK](https://jsr.io/@openstatus/sdk-node) - Build on top of openstatus with our SDK
- [shadcn/ui Documentation](https://ui.shadcn.com) - Learn about the underlying component system
- [Openstatus GitHub](https://github.com/openstatusHQ/openstatus) - Star the project and contribute
-- [Component Source Code](https://github.com/openstatusHQ/openstatus/tree/main/packages/ui/src/components) - Browse the implementation
- [Theme Explorer](https://themes.openstatus.dev) - Explore community themes
## Support
diff --git a/apps/web/src/data/content.ts b/apps/web/src/data/content.ts
index 9a0f35d9a..b30ec691b 100644
--- a/apps/web/src/data/content.ts
+++ b/apps/web/src/data/content.ts
@@ -122,6 +122,10 @@ const toolsSection = {
label: page.metadata.title,
href: `/play/${page.slug}`,
})),
+ {
+ label: "Shadcn Component Registry",
+ href: "/registry",
+ },
{
label: "Theme Explorer",
href: "https://themes.openstatus.dev",
@@ -180,6 +184,10 @@ export const playSection = {
label: "Theme Explorer",
href: "https://themes.openstatus.dev",
},
+ {
+ label: "Shadcn Component Registry",
+ href: "/registry",
+ },
{
label: "All Status Codes",
href: "https://openstat.us",
diff --git a/packages/ui/src/components/blocks/status-bar.tsx b/packages/ui/src/components/blocks/status-bar.tsx
index 36ee75d99..666c7b91f 100644
--- a/packages/ui/src/components/blocks/status-bar.tsx
+++ b/packages/ui/src/components/blocks/status-bar.tsx
@@ -433,7 +433,7 @@ export function StatusBar({
return (
<div
ref={containerRef}
- className="flex h-[50px] w-full items-end"
+ className="flex h-[50px] w-full items-end gap-px"
data-slot="status-bar"
role="toolbar"
aria-label="Status tracker"
@@ -498,10 +498,7 @@ const StatusBarItem = forwardRef<HTMLDivElement, StatusBarItemProps>(
<HoverCardTrigger asChild>
<div
ref={ref}
- className={cn(
- "group relative mx-px flex h-full w-full cursor-pointer flex-col rounded-full outline-none first:ml-0 last:mr-0 hover:opacity-80 focus-visible:opacity-80 focus-visible:ring-[2px] focus-visible:ring-ring/50 data-[aria-pressed=true]:opacity-80",
- "overflow-hidden rounded-full",
- )}
+ className="group relative flex h-full flex-1 cursor-pointer flex-col outline-none hover:opacity-80 focus-visible:opacity-80 focus-visible:ring-[2px] focus-visible:ring-ring/50 data-[aria-pressed=true]:opacity-80 rounded-full"
onClick={() => handlers.onClick(index)}
onFocus={() => handlers.onFocus(index)}
onBlur={handlers.onBlur}
@@ -515,25 +512,27 @@ const StatusBarItem = forwardRef<HTMLDivElement, StatusBarItemProps>(
aria-expanded={isActive}
data-slot="status-bar-item"
>
- {/* Render bar segments */}
- {item.bar.map((segment, segmentIndex) => {
- if (renderBar) {
- return renderBar(segment, segmentIndex);
- }
- return (
- <div
- key={`${item.day}-${segment.status}-${segmentIndex}`}
- className={cn("w-full transition-all", {
- "rounded-t-full": segmentIndex === 0,
- "rounded-b-full": segmentIndex === item.bar.length - 1,
- })}
- style={{
- height: `${segment.height}%`,
- backgroundColor: statusColors[segment.status],
- }}
- />
- );
- })}
+ <div className="flex h-full w-full flex-col overflow-hidden rounded-full">
+ {/* Render bar segments */}
+ {item.bar.map((segment, segmentIndex) => {
+ if (renderBar) {
+ return renderBar(segment, segmentIndex);
+ }
+ return (
+ <div
+ key={`${item.day}-${segment.status}-${segmentIndex}`}
+ className={cn("w-full transition-all", {
+ "rounded-t-full": segmentIndex === 0,
+ "rounded-b-full": segmentIndex === item.bar.length - 1,
+ })}
+ style={{
+ height: `${segment.height}%`,
+ backgroundColor: statusColors[segment.status],
+ }}
+ />
+ );
+ })}
+ </div>
</div>
</HoverCardTrigger>
<HoverCardContent
diff --git a/packages/ui/src/components/blocks/status-component-group.tsx b/packages/ui/src/components/blocks/status-component-group.tsx
index 8d6f7274a..243a65ebd 100644
--- a/packages/ui/src/components/blocks/status-component-group.tsx
+++ b/packages/ui/src/components/blocks/status-component-group.tsx
@@ -134,9 +134,10 @@ export function StatusComponentGroup({
}, []);
return (
- <div data-slot="status-component-group" {...props}>
+ <div {...props}>
<Collapsible
defaultOpen={defaultOpen}
+ data-slot="status-component-group"
className={cn(
"-mx-3",
"rounded-lg border border-transparent bg-muted/50 hover:border-border/50 data-[state=open]:border-border/50 data-[state=open]:bg-muted/50",