This page is for working on Crosslink, or for running its examples while
building against it. If you are only consuming the published packages, you need
Your First App instead.
Requirements
- Node.js >= 20.19 (22 recommended)
- npm (the repo uses npm workspaces)
Layout
Each workspace under packages/, adapters/ and services/ has the same two
scripts: build and typecheck.
Build, typecheck, test
Packages consume each other through their built dist/, not through TypeScript
project references. After changing a package that another one imports, rebuild
it — npm run build -w @crosslink/core — or the consumer will typecheck against
stale declarations. A TS2353: object literal may only specify known properties
on an option you just added is almost always this.
Running the examples
Cross-network variants:
The usual loop is two terminals: one host workspace running its dev script,
and one client workspace or browser tab, then scan the printed QR with a phone
on the same Wi-Fi. Nothing else needs to be running.
Checking reachability
It runs the same discovery a host runs at startup and prints what each router
protocol answered, so you can tell a Crosslink bug from a router that refuses
mappings. See Remote Access.
Testing
Both SDKs are unit-testable with no network. @crosslink/sdk-browser exports
MockSocket, an in-memory WsLike pair, so a test can drive a real
HostPairingManager and HostAcceptor and produce every failure deliberately —
a revoked device, a mismatched SAS, a dropped session mid-request.
Two rules keep the suite fast and honest:
- Never touch the real network in a unit test. Anything that would negotiate
a router mapping must be mocked —
vi.mock("@crosslink/nat-map", …) — or the
test’s result depends on the machine it runs on and takes seconds instead of
milliseconds.
- Assert on the diagnostics, not just the outcome. A host that reports
reachable: false with the right reason is a passing test; one that reports it
with no attempts recorded is a bug that will reach a user as an empty error.
Working on the docs
The documentation site is Mintlify, rooted at docs/. docs/docs.json is the
only configuration file — page paths in its navigation.groups are relative to
docs/, and every in-page link (/guides/remote-access) is too.
Adding a page means creating the .mdx file with title and description
frontmatter and listing it in docs/docs.json. A page that is not listed
does not appear in the sidebar, and Mintlify will not warn you. 