Primeiros passos

npm install regua

Prefere que o seu agente de código faça isso? Copie o prompt de instalação: ele descobre o framework, monta a Régua no lugar certo, só em desenvolvimento, e confere o build.

import { Regua } from "regua"

export function App() {
  return (
    <>
      <YourApp />
      <Regua />
    </>
  )
}

<Regua /> não renderiza nada no servidor nem durante a hidratação. No cliente, monta um portal em document.body (ou em portalTarget) e injeta os próprios estilos, todos com prefixo, sem tocar no CSS da página. Requer React 18 ou mais recente.

Funciona no App Router e no Pages Router. No App Router, importe direto num Server Component, como o app/layout.tsx: o componente já vem marcado com "use client", então não é preciso criar um wrapper.

// app/layout.tsx
import { Regua } from "regua"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR">
      <body>
        {children}
        {process.env.NODE_ENV === "development" && <Regua />}
      </body>
    </html>
  )
}

As outras exportações de regua (persistência, tipos, constantes) continuam utilizáveis no servidor. Só o componente cruza a fronteira de cliente.

regua/element traz a Régua sem exigir React no seu projeto: o React vai embutido, em build de produção. Importar o módulo não tem efeito colateral nem acessa o DOM, então é seguro em SSR (Angular SSR, Nuxt, SvelteKit). São duas formas de uso.

• mountRegua(options) monta a Régua e devolve { update, unmount }. As opções são as mesmas props do componente. update mescla as opções novas com as atuais; passe undefined para voltar uma delas ao padrão. No servidor, retorna um handle inerte.
• defineReguaElement(tagName?) registra o custom element <regua-overlay> (ou a tag que você passar). O registro é explícito, não acontece no import, e chamar de novo para a mesma tag é seguro.

Num app React, use regua, não regua/element: o elemento traz uma cópia própria do React.

Com mountRegua, num componente standalone. afterNextRender só roda no navegador, o import dinâmico mantém a Régua fora do bundle inicial e runOutsideAngular impede que os eventos da Régua disparem change detection em apps com zone.js.

import { Component, DestroyRef, NgZone, afterNextRender, inject } from "@angular/core"
import type { ReguaHandle } from "regua/element"

@Component({ selector: "app-regua", template: "" })
export class ReguaComponent {
  constructor() {
    const zone = inject(NgZone)
    let handle: ReguaHandle | undefined
    let destroyed = false

    afterNextRender(async () => {
      const { mountRegua } = await import("regua/element")
      if (!destroyed) handle = zone.runOutsideAngular(() => mountRegua({ theme: "dark" }))
    })

    inject(DestroyRef).onDestroy(() => {
      destroyed = true
      handle?.unmount()
    })
  }
}

Também dá para usar o custom element, com CUSTOM_ELEMENTS_SCHEMA no componente e defineReguaElement() no main.ts:

// main.ts
import("regua/element").then(({ defineReguaElement }) => defineReguaElement())

<regua-overlay theme="dark" [highlightColor]="cor" />

<script setup lang="ts">
import { onMounted, onBeforeUnmount } from "vue"
import { mountRegua, type ReguaHandle } from "regua/element"

let handle: ReguaHandle | undefined
onMounted(() => (handle = mountRegua({ theme: "dark" })))
onBeforeUnmount(() => handle?.unmount())
</script>

Para usar <regua-overlay> nos templates, avise o compilador do Vue que é um custom element (compilerOptions.isCustomElement: (tag) => tag === "regua-overlay") e chame defineReguaElement() no cliente.

<regua-overlay theme="dark"></regua-overlay>

<script type="module">
  import { defineReguaElement } from "https://cdn.jsdelivr.net/npm/regua@0.1.0/dist/element.js"
  defineReguaElement()
</script>

Com bundler, import { defineReguaElement } from "regua/element". O elemento monta ao entrar no documento e desmonta ao sair. Mover o elemento de lugar não reinicia a Régua.

Toda prop é também uma propriedade do elemento, em camelCase (el.features = { rulers: false }). As de valor simples também são atributos, em kebab-case (highlight-color, persist-on-reload, color-picker-formats="hex oklch").

• Props: cores, tema, persistência e o que dá para desligar.
• Atalhos: cada ferramenta tem uma tecla.
• Privacidade: o que fica guardado, e onde.