Installation
Which install path to take, what each one assumes, and the four things every path has to get right.
Overview
There are four install paths and they differ less than you would expect. Every one of them does the same four things; the pages differ only in where those four things go in your particular framework.
Pre-release, and no published host yet
Every catalogue row is implemented and installable, and their registry items
carry the whole of the source shadcn add copies.
Registry says what each item holds. Two things
are still absent, and they fail differently. There is no npm package and there
will not be one, because distribution is registry copy-in.
opsinjs.pensievelabs.org, the host every command in this section names, is also
not serving yet, so @opsinjs resolves only against a registry you point it at
yourself. Every opsinjs component has been audited against WCAG 2.2 AA, but the
audit was run by the authors, not an independent reviewer, and no component has
had a clinical review. shipped means the source installs and passed that
author-run audit; it does not mean an independent accessibility review or a
clinical review has happened, and
ADR 0025 says what
the audit covered. Nothing here is for a production health surface until a
clinician signs it.
Pick your path
| Path | Take it when | Page |
|---|---|---|
| Framework | You are starting or already have a React 19 + Tailwind v4 app | Next.js · Vite · React Router · TanStack Start · Astro |
| Existing project | You already have shadcn/ui components and a components.json | components.json |
| Manual | No CLI: you want to see exactly what lands and put it there yourself | Manual |
| Monorepo | The app that consumes opsinjs is not the repository root | Monorepo |
If you already have a working React 19 and Tailwind v4 application, go straight to components.json. The framework pages are mostly about getting to that point.
Understand the four things every path does
Knowing these makes every install page short, and makes a failure diagnosable without reading any of them.
Copy source into your repository
opsinjs is distributed as a shadcn-spec registry under the @opsinjs namespace.
shadcn add copies real .tsx files into your project. You own them from that
moment: no dependency to upgrade, no black box, and no silent change.
Registry.
Add the token layer to your stylesheet, in the right position
The tokens are CSS custom properties, not JavaScript. They must be imported after Tailwind and after any base reset, and before your own overrides. CSS order is load-bearing throughout opsinjs, and getting it wrong produces components that lay out correctly and are the wrong colour.
Make Tailwind scan the directory you copied into
Tailwind v4 generates only the classes it can find in declared sources. Because
the components live in your repository rather than in node_modules, the
directory holding them needs an @source line. Omitting it produces a component
with no styling at all, and it is the most common setup failure in this system.
Set the theme mode as a class
There is no provider to mount. Light and dark are a class on the root element and the tokens do the rest, which is what makes server rendering straightforward and why there is no theme flash to work around.
That is the entire integration surface. Anything else on the framework pages is about that framework, not about opsinjs.
Know what you need before you start
- React 19 or later. React 18 is not supported.
- Tailwind CSS v4. There is no v3 path.
- A current Node LTS for the CLI.
- Control over stylesheet order. If your framework or platform injects CSS in an order you cannot influence, opsinjs will be difficult to use with it.
Framework support explains why each of these is a hard requirement rather than a preference.
Verify it worked
The same four checks work on every path, in this order. Each one isolates a different failure:
- The file exists where
components.jsonsaid it would. - It compiles, and its imports resolve.
- It is styled. Unstyled means Tailwind is not scanning the directory.
- Its colours come from custom properties, not literals. Literals mean the token layer is missing or in the wrong position.
Troubleshooting
The command fails to resolve @opsinjs. Either components.json has no
registries entry for the namespace, or it has one pointing at
opsinjs.pensievelabs.org, which is not serving yet. The two produce different
errors. One is an unknown
registry, the other a network failure, and
Troubleshooting separates them.
Everything works except the styling. Almost certainly the @source line. This
is a Tailwind configuration fact and no opsinjs setting changes it.
Monorepo has the exact lines.
Files land somewhere unexpected. components.json aliases and your
tsconfig.json paths disagree. components.json.
Your framework is not listed. If it runs React 19 and Tailwind v4 and lets you control stylesheet order, follow Manual and tell us what you had to do differently.
Next
- Next.js is the reference install, and the one to read even if you use something else.
- components.json covers every field opsinjs reads.
- Quick start says what to build once the pieces are in place.