Tigrbl Lens

Purpose

Tigrbl Lens is a JSON-RPC 2.0 documentation viewer and playground built around the OpenRPC specification. It provides a rich UI for exploring OpenRPC documents, testing methods, and sharing API documentation with teams and users.

Repository layout

• client/: the interactive viewer and playground application.
• lander/: the marketing site and documentation lander.
• docker-compose.yml: container build definitions for the client and lander.

Usage

Run the viewer (client)

cd client
npm install
npm run dev

Run the lander site

cd lander
npm install
npm run dev

Build container images

docker compose up --build

Deploy the demo client container

docker compose up --build -d client
docker compose ps client

The demo client deploys as container tigrbl_lens_client.

Verify demo container deployment

Use this quick check to confirm the expected container name and state:

docker ps --filter "name=tigrbl_lens_client" --format "{{.Names}}\t{{.Status}}"

Implementation guidance

Build outputs

The client now supports two explicit build targets:

• npm run build:demo → static demo application output for Docker/nginx.
• npm run build:lib → distributable library artifacts for npm/CDN usage.
• npm run build → runs both targets.

NPM install (TSX/ESM import)

Install from npm and import in your React app.

npm install @tigrbljs/tigrbl-lens

import React from 'react';
import { EmbeddedLens } from '@tigrbljs/tigrbl-lens';

export default function App() {
  return <EmbeddedLens url="/openrpc.json" />;
}

This path is ideal for TSX projects where you bundle dependencies during application build.

Lens exports: when to use each component

Tigrbl Lens ships three component exports with different control levels:

• EmbeddedLens (recommended for customer embeds)
  • Enforces mode="embedded" and showLoadSpec={false}.
  • Use this for production embeds where users should only view your hosted spec.
• DemoLens (recommended for demos/sandbox)
  • Enforces mode="demo" and showLoadSpec={true}.
  • Use this for your public demo environments where loading custom JSON is desired.
• Lens (advanced/runtime configurable)
  • Exposes all props including mode and showLoadSpec.
  • Use this if your host app intentionally needs to switch behavior at runtime.

import { EmbeddedLens, DemoLens, Lens } from '@tigrbljs/tigrbl-lens';

// 1) Locked embedded behavior
<EmbeddedLens url="https://example.com/openrpc.json" />

// 2) Locked demo behavior
<DemoLens rawSpecHref="/openrpc.json" />

// 3) Runtime-configurable behavior
<Lens mode="embedded" showLoadSpec={false} url="https://example.com/openrpc.json" />

Security note: browser users can always tamper with client-side JavaScript using devtools. Treat mode/visibility flags as UX controls only. Enforce API authorization, origin restrictions, and rate limiting on the server side.

Embedded mode props

By default, Lens runs in embedded mode. Use the props below to control what users can do in an embedded integration.

• mode?: 'demo' | 'embedded'
  • embedded (default): hides the upload/load-spec UI and is best for hosted docs embeds.
  • demo: enables the demo affordances (for example the Load Spec dialog).
• showRawSpecDownload?: boolean (default: true)
  • Controls whether the Raw Spec download button appears in the top bar.
• showLoadSpec?: boolean (default: true)
  • Controls whether the Load Spec button/dialog is available in demo mode.
  • Set showLoadSpec={false} when you want users to rely only on your published OpenRPC URL.
• rawSpecHref?: string
  • Sets the sidebar Raw OpenRPC Document link target.
  • If omitted, Lens falls back to url, then /openrpc.json.

Embedded: lock to hosted spec URL

Use this when you want a read-only embed where users can only open/download your hosted spec reference.

import React from 'react';
import { EmbeddedLens } from '@tigrbljs/tigrbl-lens';

export default function App() {
  return (
    <EmbeddedLens
      url="https://example.com/openrpc.json"
      rawSpecHref="https://example.com/openrpc.json"
      showRawSpecDownload={true}
    />
  );
}

Implementing the Tigrbl Lens CSS

Tigrbl Lens ships its base styles as @tigrbljs/tigrbl-lens/styles.css. Import this stylesheet once in your host app before rendering <Lens />.

Bundled app (Vite, Next.js, CRA, etc.)

Import the CSS from your entry module (main.tsx, index.tsx, etc.):

import '@tigrbljs/tigrbl-lens/styles.css';
import { EmbeddedLens } from '@tigrbljs/tigrbl-lens';

Plain HTML / CDN setup

Load the package stylesheet in <head> and then mount the component:

<link
  rel="stylesheet"
  href="https://esm.sh/@tigrbljs/tigrbl-lens@<version>/dist/tigrbl-lens.css"
/>

Without this stylesheet, the component still renders but loses layout and theme styling.

CDN usage (TSX import)

Use an npm-backed ESM CDN (for example esm.sh) and import directly.

import React from 'https://esm.sh/[email protected]';
import ReactDOM from 'https://esm.sh/[email protected]/client';
import { EmbeddedLens } from 'https://esm.sh/@tigrbljs/tigrbl-lens@<version>';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <EmbeddedLens url="/openrpc.json" />
  </React.StrictMode>
);

This path is ideal when you still author TSX modules but want to consume the package via CDN-hosted ESM.

CDN usage (HTML + importmap)

You can also run without a bundler by using type="module" and an import map.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Tigrbl Lens CDN</title>
    <script type="importmap">
      {
        "imports": {
          "react": "https://esm.sh/[email protected]",
          "react-dom/client": "https://esm.sh/[email protected]/client",
          "@tigrbljs/tigrbl-lens": "https://esm.sh/@tigrbljs/tigrbl-lens@<version>"
        }
      }
    </script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module">
      import React from 'react';
      import ReactDOM from 'react-dom/client';
      import { EmbeddedLens } from '@tigrbljs/tigrbl-lens';

      ReactDOM.createRoot(document.getElementById('root')).render(
        React.createElement(EmbeddedLens, { url: '/openrpc.json' })
      );
    </script>
  </body>
</html>

This path is ideal for plain HTML deployments that rely on native browser modules and import maps.

Maintainer guidance

Styles and structure

• Use TypeScript + React functional components.
• Keep styling consistent with the existing Tailwind utility classes and component patterns.
• Prefer lucide-react icons for UI affordances to match the existing visual language.

Contributing workflow

1. Create a branch for your work.
2. Keep client/ and lander/ changes scoped to the relevant app.
3. Update docs and links (see below) when behavior or navigation changes.

Updating documentation within the lander

The landing-site docs live in lander/data/docs.ts. Update the markdown content there, and keep structure consistent with the DocSection layout used by lander/components/Docs.tsx.

Linking the lander to the correct pages

The lander navigation and CTA links should always point at the current destinations:

• Demo and Playground should link to the deployed viewer experience (or the correct in-page anchor if you intentionally keep it internal).
• Installs should link to the installation section, currently driven by lander/components/Installation.tsx and lander/components/Navbar.tsx.
• GitHub should link to the current repository URL in lander/components/Navbar.tsx and lander/components/Footer.tsx.

Review lander/components/Navbar.tsx, lander/components/Hero.tsx, and lander/components/Footer.tsx whenever navigation targets change to keep all entry points aligned.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.