lexification-server

Migrates service packages from legacy lex gen-server codegen to @atproto/lex and @atproto/xrpc-server.

9.6k|915|Updated Dec 17, 2021
One-click install
npx skills add https://github.com/bluesky-social/atproto --skill lexification-server
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: lexification-server
Source: https://github.com/bluesky-social/atproto/tree/main/.agents/skills/lexification-server
Command: npx skills add https://github.com/bluesky-social/atproto --skill lexification-server

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Service packages in the atproto monorepo still running on the legacy server stack — lex gen-server codegen, a committed src/lexicon/ tree, and server.<ns>.<method>() route chains — need a structured, behavior-preserving migration onto @atproto/lex schemas and @atproto/xrpc-server routing without breaking working runtime logic.

Core Features & Use Cases

  • Project config migration: Replaces lex gen-server with lex build, fixes dependencies, updates gitignore, and deletes the legacy src/lexicon/ tree.
  • Route and type migration: Converts server.<ns>.<method>(…) registrations to server.add(schema, …) and maps legacy generated types (QueryParams, OutputSchema, isX guards, ids.* constants) to $-accessors like $Params, $OutputBody, $isTypeOf, and $lxm.
  • Use Case: Migrating packages/ozone — the last unmigrated service — by following the already-migrated packages/pds and packages/bsky as reference patterns, one namespace of route files at a time.

Quick Start

Migrate the ozone package's server stack off lex gen-server onto @atproto/lex and @atproto/xrpc-server, starting with project config and then route files one namespace at a time.

Frequently Asked Questions about lexification-server

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate a package from lex gen-server to @atproto/lex?

Replace the codegen script with `lex build --clear --indexFile --lexicons ../../lexicons`, swap dependencies to `@atproto/lex` and `@atproto/xrpc-server`, delete the gitignored `src/lexicon/` tree, then convert route files one namespace at a time from `server.<ns>.<method>()` to `server.add(schema, …)`.

What is the difference between $isTypeOf and $matches in @atproto/lex?

$isTypeOf reads only the `$type` tag and acts as a TypeScript type predicate, matching the behavior of legacy `isX()` guards. $matches validates the entire value against the schema and is correct for unvalidated data like firehose records or datastore values.

When should I use $type vs $lxm vs $nsid accessors?

Use `$type` for record and object type strings such as collections and union tags, `$lxm` for XRPC method ids in auth and proxy checks, and `$nsid` for defs documents that define no main type. They can hold identical strings, so a wrong choice type-checks but fails at runtime.

Why does my migrated package fail with 'Cannot find module ../lexicons/index.js'?

The generated `src/lexicons/` directory is gitignored and does not exist until codegen runs. Run `pnpm run codegen` or a build to generate it; the error means codegen has not run, not that the import path is wrong.

Should tests be migrated off AtpAgent during a server lexification?

No. Test call sites deliberately keep using `AtpAgent` so tests act as a regression check that the migration did not change behavior. Only test imports of types or constants from the deleted `src/lexicon/` tree must move, either to `../../src/lexicons/index.js` or to legacy equivalents in `@atproto/api`.