Because @seed-hypermedia/client currently looks like an internal package that happens to be public, not like a product developers are being invited to adopt.
The strongest signal is brutally simple: the npm package says it has no README. A developer arriving from npm cannot discover what it does, what they can build, what infrastructure it requires, or see a working example. (NPM)
The main reasons
1. There is no concrete developer promise
“Seed Hypermedia client” does not answer:
What useful application can I build with this package today?
Developers need promises such as:
Build a collaborative knowledge app.
Publish versioned documents from TypeScript.
Read and traverse a decentralized knowledge graph.
Add permanent links, citations, and transclusions to your application.
Give an AI agent access to a user-owned knowledge base.
At present, the public positioning describes the Seed application and protocol, not a clearly bounded SDK product. The repository says Seed provides identities, version control, semantic documents, multimedia, and organizations, but it does not turn those capabilities into an external developer journey. (GitHub)
2. The package has no visible “five-minute success”
A developer should be able to copy this:
import {createClient} from '@seed-hypermedia/client'
const seed = createClient({
endpoint: 'https://example.hyper.media',
})
const document = await seed.documents.get(
'hm://z6Mk.../research/paper',
)
console.log(document.title)
And then quickly progress to:
await seed.documents.create({
title: 'Research Notes',
content: [
{
type: 'paragraph',
text: 'My first Seed document',
},
],
})
Whether those are the eventual APIs is secondary. The missing piece is a small, obvious path from installation to visible value.
3. It is unclear what the client actually connects to
A prospective developer cannot easily determine:
Does it work directly in a browser?
Does it connect to a public Seed site?
Does it require the desktop daemon?
Does the developer need to run a P2P node?
Can it write, or only read?
How are identities and signing handled?
Can it work remotely?
Is it usable from Node.js, Next.js, Bun, Cloudflare Workers, or React Native?
Who stores and replicates the resulting data?
The main repository explains that Seed sites require both a daemon containing the P2P node and a frontend, and recommends Docker Compose for deployment. That makes external adoption appear operationally substantial. (GitHub)
This is inherent to some extent: Seed is not merely an HTTP database. It involves cooperating processes, communication channels, local state, and messages—the fundamental complexity of distributed systems. But the SDK must hide that complexity for the default case.
4. The version communicates instability
A 0.0.x version tells developers:
This API may change at any moment.
The npm result currently shows active publication, which is good, but rapid 0.0.x releases can reinforce the impression that this is generated or internal code rather than a supported public interface. (NPM)
The repository itself explicitly warns that the software has rough edges, documentation is missing, and users should keep copies of valuable content. That is honest, but it discourages developers from basing applications on it. (GitHub)
5. There are no external reference applications
Search results mostly expose usage inside Seed’s own monorepo, such as imports from @seed-hypermedia/client/hm-types. (GitHub)
That makes the package look like:
Shared frontend code extracted from the Seed application.
Rather than:
The supported way for third parties to build on the Hypermedia network.
Developers imitate other developers. They need at least three small, independent examples:
Seed Reader — render any Seed document in Next.js.
Research Agent — monitor a space and process newly published papers.
Knowledge Board — query documents and project them as cards.
6. The package boundary probably exposes Seed’s internal mental model
Imports such as:
@seed-hypermedia/client/hm-types
@seed-hypermedia/client/hmblock-to-editorblock
suggest a package containing many internal utilities and representations rather than one intentional public API. (GitHub)
External developers should not have to understand:
internal block conversion,
daemon RPC types,
frontend resource types,
draft implementation details,
application-specific query wrappers.
They need a small domain API:
client.documents.get()
client.documents.create()
client.documents.update()
client.documents.query()
client.accounts.get()
client.comments.create()
client.network.subscribe()
Internals can remain available under explicitly unstable paths, but the top-level package should be designed around external tasks.
7. Discovery is nearly nonexistent
Searching for the exact package produces little beyond npm and Seed’s own code. There are no tutorials, blog posts, Stack Overflow answers, integrations, videos, starter repositories, or community examples.
Even developers interested in decentralized applications are unlikely to search for the exact package name. They search for problems:
decentralized CMS TypeScript
local-first knowledge graph SDK
versioned document API
permanent links SDK
collaborative publishing backend
knowledge base for AI agents
Seed must appear in those problem spaces.
The deeper issue
You have published the implementation before defining the developer product.
The package answers:
How can Seed’s own TypeScript applications share protocol-related code?
It does not yet answer:
Why should an independent developer build their next application on Seed rather than PostgreSQL, Git, IPFS, Notion’s API, or a conventional CMS?
That requires a clear wedge. I think the strongest initial wedge is:
A versioned, user-owned knowledge backend for agents and collaborative applications.
Not “build decentralized software” in the abstract.
What I would do first
Package proposition
Build applications on user-owned, versioned knowledge.
Read, create, link, query, and subscribe to Seed documents from TypeScript.
Public API
Create a deliberately small package:
@seed-hypermedia/client
├── createClient
├── documents
├── accounts
├── comments
├── queries
└── subscriptions
Move lower-level pieces to:
@seed-hypermedia/protocol
@seed-hypermedia/types
@seed-hypermedia/editor
@seed-hypermedia/client/internal
README opening
# Seed Hypermedia TypeScript Client
Build applications on user-owned, versioned knowledge.
The Seed client lets browser and Node.js applications:
- Read and publish structured documents
- Create permanent links to documents and blocks
- Query distributed knowledge spaces
- Track versions and authorship
- Subscribe to changes
- Act on behalf of cryptographic identities
Immediately follow it with one installation command, one executable example, and one screenshot or deployed demo.
The metric that matters
Do not initially measure npm downloads—they may include your own builds.
Measure:
How many external developers reach their first successful document read or write without speaking to the Seed team?
Right now, I suspect the answer is effectively zero because the package has no explicit entrance, path, or destination. The technology may already be capable; the developer experience has not yet been packaged as a product.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime