Skip to content

opensite-ai/opensite-skills / page-speed-library

page-speed-library

Verified

page-speed-* library development patterns. Use when creating or modifying @page-speed/* packages (blocks, router, forms, img, video, skins, maps, icon, lightbox, pdf-viewer, venn-diagram, hooks, social-share, humanizer) or the opensite-hooks and pressable libraries. Covers tsup bundling, peer dependency management, and the sub-library architecture.

Page-Speed Library Development Skill

Skill Resources

You are working in the OpenSite @page-speed/* sub-library ecosystem — a set of focused, tree-shakable React component packages that compose into @opensite/ui and work together to deliver OpenSite's groundbreaking Semantic UI Design System.

Library Inventory

PackagePurposeKey Dependency
@page-speed/blocksPre-compiled Tailwind CSS rendering runtime@opensite/ui
@page-speed/routerSPA routing for site builder pagesReact
@page-speed/formsForm components with validationReact Hook Form
@page-speed/imgOptimized image componentReact
@page-speed/videoVideo player/embed componentReact
@page-speed/skinsTheme/skin CSS variable systemCSS
@page-speed/mapsMapLibre GL map componentmaplibre-gl
@page-speed/iconSVG icon systemReact
@page-speed/lightboxImage/media lightboxReact
@page-speed/pdf-viewerPDF rendering in browserReact
@page-speed/venn-diagramVenn diagram visualizationReact
@page-speed/hooksShared React hooksReact
@page-speed/social-shareSocial sharing buttonsReact
@page-speed/humanizerAI content humanization (in progress)React
@opensite/hooksCore OpenSite hooks libraryReact
pressableAccessible press/click abstractionReact

Standard tsup Configuration

Every @page-speed/* library uses this base tsup config:

// tsup.config.ts
import { defineConfig } from "tsup"

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["cjs", "esm"],
  dts: true,
  splitting: true,
  sourcemap: true,
  clean: true,
  treeshake: true,
  external: [
    "react",
    "react-dom",
    // Add any other peerDeps here
  ],
  esbuildOptions(options) {
    options.banner = {
      js: '"use client"',  // Required for Next.js RSC compatibility
    }
  },
})

Package.json Template

{
  "name": "@page-speed/your-package",
  "version": "0.1.0",
  "description": "Short description of what this package does",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "sideEffects": false,
  "peerDependencies": {
    "react": ">=17.0.0",
    "react-dom": ">=17.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.3.3",
    "@types/react-dom": "^18.3.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "tsup": "^8.0.1",
    "typescript": "^5.6.2",
    "vitest": "^3.0.0"
  },
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest",
    "type-check": "tsc --noEmit"
  }
}

src/index.ts Export Pattern

Every package exports from a central src/index.ts. Keep it flat and explicit:

// src/index.ts — named exports only, no barrel re-exports of internal utils
export { YourComponent, type YourComponentProps } from "./components/YourComponent"
export { AnotherComponent, type AnotherComponentProps } from "./components/AnotherComponent"
export { useYourHook } from "./hooks/useYourHook"
export type { SharedType } from "./types"

// Never export internal utilities that consumers shouldn't use
// Never use: export * from "./components"  (breaks tree-shaking)

Component Pattern for Library Components

Library components should be:

  1. Framework-agnostic styled (no Tailwind in lib components — let consumer apply classes)
  2. Fully typed with exported prop types
  3. Accessible (ARIA attributes, keyboard navigation)
  4. Forwardable refs when wrapping DOM elements
// src/components/YourComponent.tsx
"use client"  // Required for Next.js App Router compatibility

import React from "react"

export interface YourComponentProps
  extends React.HTMLAttributes<HTMLDivElement> {
  /** Primary content */
  children: React.ReactNode
  /** Optional secondary content */
  label?: string
  /** Controlled open state */
  isOpen?: boolean
  /** Callback when state changes */
  onOpenChange?: (open: boolean) => void
}

export const YourComponent = React.forwardRef<HTMLDivElement, YourComponentProps>(
  ({ children, label, isOpen, onOpenChange, className, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={className}
        role="region"
        aria-label={label}
        {...props}
      >
        {children}
      </div>
    )
  }
)
YourComponent.displayName = "YourComponent"

@page-speed/img Deep Dive

@page-speed/img is used everywhere. Key usage patterns:

import { Img, type ImgProps } from "@page-speed/img"

// Basic image with lazy loading
<Img
  src="https://example.com/image.jpg"
  alt="Description"
  width={800}
  height={450}
  className="w-full h-auto"
/>

// Fill container (parent must be relative + overflow-hidden)
<div className="relative h-64 overflow-hidden">
  <Img
    src={imageUrl}
    alt={alt}
    fill
    className="object-cover object-center"
  />
</div>

// With blur placeholder
<Img
  src={src}
  alt={alt}
  width={400}
  height={300}
  placeholder="blur"
  blurDataURL={blurDataUrl}
/>

@page-speed/hooks Usage

import {
  useIntersectionObserver,
  useMediaQuery,
  useLocalStorage,
  useDebounce,
  useClickOutside,
} from "@page-speed/hooks"

// Intersection observer for lazy loading/animations
const { ref, isIntersecting } = useIntersectionObserver({
  threshold: 0.1,
  rootMargin: "50px",
})

// Responsive breakpoint detection
const isMobile = useMediaQuery("(max-width: 768px)")
const isTablet = useMediaQuery("(min-width: 768px) and (max-width: 1024px)")

// Click outside detection
const containerRef = useRef<HTMLDivElement>(null)
useClickOutside(containerRef, () => setIsOpen(false))

@opensite/hooks Usage

import {
  useSiteContext,
  useComponentRegistry,
  useTheme,
  useSkin,
} from "@opensite/hooks"

// Access the current site context (for site builder components)
const { siteId, accountId, locale } = useSiteContext()

// Access the component registry (for dynamic rendering)
const { getComponent, registerComponent } = useComponentRegistry()

// Access the current theme
const { theme, setTheme } = useTheme()

// Access and apply skins
const { currentSkin, applySkin } = useSkin()

Testing Pattern for Libraries

// src/__tests__/YourComponent.test.tsx
import { render, screen } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import { describe, it, expect, vi } from "vitest"
import { YourComponent } from "../components/YourComponent"

describe("YourComponent", () => {
  it("renders children", () => {
    render(<YourComponent>Content</YourComponent>)
    expect(screen.getByText("Content")).toBeInTheDocument()
  })

  it("calls onOpenChange when triggered", async () => {
    const onOpenChange = vi.fn()
    render(<YourComponent onOpenChange={onOpenChange}>Click me</YourComponent>)
    await userEvent.click(screen.getByText("Click me"))
    expect(onOpenChange).toHaveBeenCalledWith(true)
  })

  it("forwards ref to DOM element", () => {
    const ref = React.createRef<HTMLDivElement>()
    render(<YourComponent ref={ref}>Content</YourComponent>)
    expect(ref.current).toBeInstanceOf(HTMLDivElement)
  })
})

Version Publishing Checklist

Before publishing a new version:

  • Run pnpm build — ensure no type errors
  • Run pnpm test — all tests pass
  • Check bundle size with size-limit (if configured)
  • Verify exports are tree-shakable (import one component, bundle size should be minimal)
  • Update CHANGELOG.md with breaking changes
  • Bump version in package.json
  • Test in the ui-library showcase before publishing
  • Ensure peer deps are not bundled (check dist/index.js for React imports)

pressable Library

pressable is an accessibility-first press/tap interaction library:

import { Pressable, usePressable } from "@page-speed/pressable"

// Declarative usage
<Pressable
  onPress={() => handlePress()}
  onLongPress={() => handleLongPress()}
  disabled={isLoading}
>
  {({ isPressed }) => (
    <div className={cn("cursor-pointer", isPressed && "scale-95 transition-transform")}>
      Press me
    </div>
  )}
</Pressable>
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall