Troubleshooting

Import @spry/theme/tailwind.css in your root layout or a top-level client entry so tokens and theme rules load before any Spry component renders. Keep SpryProvider in a client component above interactive routes.

If a page is a Server Component by default, any subtree that needs theme context or client-only hooks must be a Client Component or rendered under a client provider boundary.

Errors such as “createContext is not a function” or invalid hook usage during static rendering usually mean a client module was imported from a file the bundler treats as a server component. Fixes:

• Add "use client" at the top of the file that uses context or hooks.
• Move providers (theme, toast) into providers.tsx with "use client" and import that from layout.tsx.
• Avoid re-exporting client components from a barrel that server components import widely.

The docs app uses output: "export" (pure static HTML + JS). Interactive UI (buttons, search, theme toggle, mobile nav) relies on the browser loading the _next/ JavaScript bundles and hydrating React.

If you deploy under a subpath — for example https://username.github.io/SpryDesign/ — you must set the same path when you build, or the browser requests scripts from the wrong URL (404), hydration never runs, and nothing interactive works.

Build with NEXT_PUBLIC_BASE_PATH matching that folder (no trailing slash):

Serve over HTTP(S); opening exported files via file:// will not run the client bundle correctly. For a root domain deploy (e.g. docs.example.com at /), no base path is needed.

Confirm the Tailwind / PostCSS pipeline includes @spry/theme/tailwind.css and that content scanning covers node_modules/@spry/ui (the theme entry documents @source paths). Hard-refresh after changing global imports.

Spry targets evergreen browsers: last two major versions of Chrome, Firefox, Safari, and Edge. Features such as color-mix() and oklab are used in theme CSS; very old browsers without modern color support may need a reduced theme or fallbacks (not shipped by default).

Internet Explorer is not supported.