Skip to content

Latest commit

 

History

History
100 lines (80 loc) · 4.27 KB

INSTALLATION.md

File metadata and controls

100 lines (80 loc) · 4.27 KB

Installation and integration

Requirements

Development: Node.js 22.13 or newer, npm, Git. Library peers: React/React DOM 18.3.1 or 19.x. Keep React and React DOM on the same version. There are no application environment variables, API keys, backend services or mandatory network access at runtime. Storage is optional (persist={false}).

The package identity is accessibility-plugin-react. Version 2 is the current major line and latest is the stable distribution tag. The API changes from the historical 1.x package require migration (see MIGRATION.md). Install the current release with npm install accessibility-plugin-react, or pin the major line with npm install accessibility-plugin-react@2. For this checkout:

npm ci
npm run build
npm pack
# From an independent application:
npm install /absolute/path/to/accessibility-plugin-react-2.0.1.tgz

Importing accessibility-plugin-react automatically injects its scoped CSS in browser environments. The standalone accessibility-plugin-react/style.css export remains available for explicit stylesheet pipelines. Do not add the library to a Tailwind content scan. No shadcn, icon or Motion dependency is needed. See README for complete React/Vite JSX.

Next.js App Router

Keep custom hooks and custom apply callbacks in a Client Component. The built library preserves its own client boundary. The root layout may remain a Server Component.

// app/preferences.tsx
"use client";
import {
  AccessibilityPlugin,
  AccessibilityButton,
  AccessibilityList,
  FontSizeController,
  GrayscaleController,
  ResetController,
} from "accessibility-plugin-react";
export default function Preferences() {
  return (
    <AccessibilityPlugin>
      <AccessibilityButton />
      <AccessibilityList>
        <FontSizeController />
        <GrayscaleController />
        <ResetController />
      </AccessibilityList>
    </AccessibilityPlugin>
  );
}
// app/layout.tsx
import type { ReactNode } from "react";
import Preferences from "./preferences";
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Preferences />
      </body>
    </html>
  );
}

Mount the widget in the persistent root layout, not each route. Do not place document reads inside render. Do not disable SSR merely to mask hydration problems. Effects and portals appear on the client after hydration; a brief default-style paint can occur.

A complete runnable example is available in examples/next-app/.

Content Security Policy (CSP)

For strict Content Security Policy environments (such as disabling inline styles or generating cryptographic nonces), see the dedicated Content Security Policy Guidance for full Next.js and Vite recipes.

Next.js Pages Router

// pages/_app.tsx
import type { AppProps } from "next/app";
import Preferences from "../components/preferences"; // same component as above
export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Preferences />
    </>
  );
}

Custom global CSS, Tailwind and themes

Load library CSS after a host reset and load intentional widget overrides afterward. There is no library global preflight. Portals are independent of application layout and filter effects. Global host styles can still affect inherited properties or override selectors, especially with !important; inspect computed styles if controls differ.

Filters create a containing block for fixed host descendants. Test sticky/fixed headers, modals, menus, images and third-party overlays in your real application. Text measurement does not enter iframe documents or Shadow DOM. Hiding videos is visual only and is not a playback-control feature. See CSP guidance and troubleshooting for CSP and font-loading considerations.

Verified consumers

Automated scripts install the packed archive into separate directories rather than importing repository source. They exercise ESM, CommonJS, declarations, SSR, production Vite builds, and production Next App/Pages routes. Exact framework/browser versions and actual results are in PROJECT_STATUS.md. Broader versions allowed by peer ranges are compatibility targets, not individually verified claims.