From 140748c1a4edbc190f160d0604f79c7fc13335d0 Mon Sep 17 00:00:00 2001 From: shrugs Date: Wed, 13 May 2026 11:40:08 -0500 Subject: [PATCH 01/17] checkpoint: quickstart --- .../src/content/docs/docs/integrate/index.mdx | 162 +++++++++++++++++- 1 file changed, 159 insertions(+), 3 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx index c9aed63f8c..3366c0dbd5 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx @@ -6,11 +6,168 @@ sidebar: order: 1 --- +import { LinkCard } from '@astrojs/starlight/components'; -:::caution[Coming Soon] -We're actively working on this page right now. Check back by May 18th for full content! + +:::tip[Prepare for ENSv2] +The ENSv2 upgrade to the ENS protocol is comming **Summer 2026**! Your app, regardless of how it interacts with names, needs to be updated to avoid being left behind. + + + Learn more about ENSv2 Readiness + ::: +ENSNode fully supports the ENSv2 upgrade via the [Omnigraph API](/docs/integrate/omnigraph), a _unified_ API over **both** ENSv1 and ENSv2. ENSNode takes the guesswork out of ENS integrations, whether you need to resolve up to date records, search all Domains, or see which Domains a user owns (and much, much more). + +TODO: insert the Omnigraph ENSv1 + ENSv2 asset here + +You can integrate with ENSNode in many different ways, whether you're using React, any Javascript runtime, or raw GraphQL. + + + +## 1. `enskit` + Omnigraph + +With `enskit`, leverage ENSNode and the Omnigraph to power your React components using `useOmnigraphQuery`. `enskit` comes with built-in type-safety, Omnigraph-specific cache directives, easy infinite pagination, and much much more. + + +```tsx +// this is fully typechecked and supports editor autocomplete! +const DomainFragment = graphql(` + fragment DomainFragment on Domain { + __typename + id + name + owner { id address } + } +`); + +// this is fully typechecked and supports editor autocomplete! +const DomainByNameQuery = graphql(` + query DomainByNameQuery($name: InterpretedName!) { + domain(by: { name: $name }) { + ...DomainFragment + subdomains { + edges { node { ...DomainFragment } } + } + } + } +`, + [DomainFragment], +); + +function RenderDomainFragment({ data }: { data: FragmentOf }) { + // type-safe access to fragment data! + const domain = readFragment(DomainFragment, data); + + return ( + <> + Name: {domain.canonical ? beautifyInterpretedName(domain.canonical.name) : 'Unnamed Domain'} + Protocol Version: {domain.__typename === 'ENSv1Domain' ? 'ENSv1' : 'ENSv2'} + Owner: {domain.owner ? domain.owner.address : 'Unowned'} + + ); +} + +export function RenderDomainAndSubdomains({ name }: { name: InterpretedName }) { + // `result` is fully typed! + const [result] = useOmnigraphQuery({ query: DomainByNameQuery, variables: { name } }); + + // some loading/error handling + if (!data && fetching) return

Loading...

; + if (error) return

Error: {error.message}

; + if (!data?.domain) return

No domain was found with name '{name}'.

; + + // now we have type-safe access to Domain! + const domain = readFragment(DomainFragment, data.domain); + const { subdomains } = data.domain; + + return ( +
+ + +

Subdomains:

+
    + {(data.domain.subdomains?.edges ?? []).map((edge) => { + const { id } = readFragment(DomainFragment, edge.node); + return ( +
  • + +
    • + ); + })} +
+
+ ); +} +``` + + + + + +## 2. `enssdk` + Omnigraph + +With `enssdk`, leverage ENSNode and the Omnigraph from any Javascript runtime to power your frontend or backend apps. `enssdk` comes with built-in type-safety and editor autocomplete for Omnigraph queries. + + +```ts +// create and extend an EnsNodeClient with Omnigraph API support +const client = createEnsNodeClient({ url: process.env.ENSNODE_URL! }).extend(omnigraph); + +// this is fully typechecked and supports editor autocomplete! +const HelloWorldQuery = graphql(` + query HelloWorld { + domain(by: { name: "eth" }) { + id + name + owner { address } + } + } +`); + +// `result` is fully typed! +const result = await client.omnigraph.query({ query: HelloWorldQuery }); +``` + + + +## 3. Omnigraph GraphQL API + +The Omnigraph API is a GraphQL API following the Relay specification, so you get built-in support for efficient infinite pagination and idomatic access to all of the ENS protocol within a _unified_ ENSv1 + ENSv2 datamodel. + +```gql +query MyDomains($address: Address!) { + account(by: { address: $address }) { + domains { + edges { + node { + label { interpreted } + canonical { name } + } + } + } + } +} +``` + + + This page will be a 60-second quickstart for querying ENSv2 data through ENSNode — including: - A **React example** with [enskit](/docs/integrate/integration-options/enskit) using the `useOmnigraphQuery` hook. @@ -18,4 +175,3 @@ This page will be a 60-second quickstart for querying ENSv2 data through ENSNode - Links to [hosted instances](/docs/integrate/hosted-instances) so you can start querying immediately with zero setup. - [ENSv2 Readiness](/docs/integrate/ensv2-readiness) — how building with ENSNode today prepares your app for ENSv2. - [Integration Options](/docs/integrate/integration-options) — choose the right path: enskit, enssdk, raw GraphQL, or ENSDb. - From dec0361bd1d619e87e0afaf8e45715ac0d7b565d Mon Sep 17 00:00:00 2001 From: shrugs Date: Wed, 13 May 2026 13:26:59 -0500 Subject: [PATCH 02/17] checkpoint: enskit --- .../src/content/docs/docs/integrate/index.mdx | 8 +- .../integrate/integration-options/enskit.mdx | 397 +++++++++++++++++- .../integrate/integration-options/index.mdx | 35 +- examples/enskit-react-example/tsconfig.json | 5 - 4 files changed, 429 insertions(+), 16 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx index 3366c0dbd5..e929e93ab6 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx @@ -21,7 +21,7 @@ ENSNode fully supports the ENSv2 upgrade via the [Omnigraph API](/docs/integrate TODO: insert the Omnigraph ENSv1 + ENSv2 asset here -You can integrate with ENSNode in many different ways, whether you're using React, any Javascript runtime, or raw GraphQL. +You can integrate with ENSNode in many different ways, whether you're using React, any JavaScript runtime, or raw GraphQL. Subdomains: