Omnigraph Quickstart & Walkthrough & Example Apps & ENSv2 Readiness

AGENTS.md

@@ -87,8 +87,8 @@ Fail fast and loudly on invalid inputs.
 
 - Add a changeset when your PR includes a logical change that should bump versions or be communicated in release notes: https://ensnode.io/docs/contributing/prs#changesets
 - Before declaring work complete, run validation in the affected project(s):
-  1. `pnpm -F <affected-project> typecheck`
-  2. `pnpm lint`
-  3. `pnpm test --project <affected-project> [--project <other-affected-project>]`
-  4. If OpenAPI Specs were affected, run `pnpm generate:openapi`
-  5. If the Omnigraph GraphQL Schema was affected, run `pnpm generate:gqlschema`
+  1. If OpenAPI Specs were affected, run `pnpm generate:openapi`
+  2. If the Omnigraph GraphQL Schema was affected, run `pnpm generate:gqlschema`
+  3. `pnpm -F <affected-project> typecheck`
+  4. `pnpm lint`
+  5. `pnpm test --project <affected-project> [--project <other-affected-project>]`

apps/ensapi/src/lib/resolution/operations.ts

@@ -110,6 +110,9 @@ export function logOperations(
   operations: Operation[],
   logger: { debug: (obj: unknown) => void },
 ): void {
+  // silence this noisy log in CI
+  if (process.env.CI) return;
+
   if (process.env.NODE_ENV !== "production") {
     console.table(tablifyOperations(operations));
   } else {

docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts

@@ -54,8 +54,8 @@ export const integrateSidebarTopic = {
           link: "/docs/integrate/integration-options/enssdk",
         },
         {
-          label: "Raw GraphQL",
-          link: "/docs/integrate/integration-options/raw-graphql",
+          label: "Omnigraph GraphQL API",
+          link: "/docs/integrate/integration-options/omnigraph-graphql-api",
         },
         {
           label: "ENSDb (PostgreSQL)",

docs/ensnode.io/src/content/docs/docs/integrate/index.mdx

@@ -6,16 +6,178 @@ 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.
+
+<a href="/docs/integrate/ensv2-readiness">
+  Learn more about ENSv2 Readiness
+</a>
 :::
 
+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.
+
+<LinkCard
+  title='Full Integration Documentation'
+  href="/docs/integrate/integration-options"
+/>
+
+## 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<typeof DomainFragment> }) {
+  // type-safe access to fragment data!
+  const domain = readFragment(DomainFragment, data);
+
+  return (
+    <>
+      <span>Name: {domain.canonical ? beautifyInterpretedName(domain.canonical.name) : 'Unnamed Domain'}</span>
+      <span>Protocol Version: {domain.__typename === 'ENSv1Domain' ? 'ENSv1' : 'ENSv2'}</span>
+      <span>Owner: {domain.owner ? domain.owner.address : 'Unowned'}</span>
+    </>
+  );
+}
+
+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 <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (!data?.domain) return <p>No domain was found with name '{name}'.</p>;
+
+  // now we have type-safe access to Domain!
+  const domain = readFragment(DomainFragment, data.domain);
+  const { subdomains } = data.domain;
+
+  return (
+    <div>
+      <RenderDomainFragment data={data.domain} />
+
+      <h2>Subdomains:</h2>
+      <ul>
+        {subdomains?.edges.map((edge) => {
+          const { id } = readFragment(DomainFragment, edge.node);
+          return (
+            <li key={id}>
+              <RenderDomainFragment data={edge.node} />
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+```
+
+<LinkCard
+  title='Full enskit Integration Documentation'
+  href="/docs/integrate/integration-options/enskit"
+/>
+
+<LinkCard
+  title="enskit-react-example app"
+  description='Check out our enskit-react-example for a full example app.'
+  href="https://github.com/namehash/ensnode/tree/main/examples/enskit-react-example"
+/>
+
+## 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 });
+```
+
+<LinkCard
+  title='Full enssdk Integration Documentation'
+  href="/docs/integrate/integration-options/enssdk"
+/>
+
+<LinkCard
+  title="enssdk-example app"
+  description='Check out our enssdk-example for a full example app.'
+  href="https://github.com/namehash/ensnode/tree/main/examples/enssdk-example"
+/>
+
+## 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 }
+        }
+      }
+    }
+  }
+}
+```
+
+<LinkCard
+  title='Full Omnigraph GraphQL API Documentation'
+  href="/docs/integrate/integration-options/omnigraph-graphql-api"
+/>
+
 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.
 - A **interactive code snippet** with [enssdk](/docs/integrate/integration-options/enssdk) showing a typed ENS Omnigraph query (e.g. look up a domain). Optionally can launch the request against the ENS Omnigraph API and see the response in your browser.
 - 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.
-