a collection of lightweight TypeScript packages for AT Protocol, the protocol powering Bluesky
atproto
bluesky
typescript
npm
docs(lex-cli): mention atcute:lexicons field
+47
-6
+47
-6
packages/lexicons/lex-cli/README.md
+47
-6
packages/lexicons/lex-cli/README.md
···
23
23
npm exec lex-cli generate -c ./lex.config.js
24
24
```
25
25
26
-
highly recommend packaging the generated schemas as a publishable library for others to use.
26
+
## publishing your schemas
27
+
28
+
if you're packaging your generated schemas as a publishable library, add the `atcute:lexicons`
29
+
field to your package.json. this allows other projects to automatically discover and import your
30
+
schemas without manual configuration.
31
+
32
+
```json
33
+
{
34
+
"name": "@example/my-schemas",
35
+
"atcute:lexicons": {
36
+
"mapping": {
37
+
"com.example.*": {
38
+
"type": "namespace",
39
+
"path": "./types/{{nsid_remainder}}"
40
+
}
41
+
}
42
+
}
43
+
}
44
+
```
45
+
46
+
the `path` field supports several template expansions:
47
+
48
+
- `./` at the start is replaced with the package name (e.g., `./types/foo` becomes
49
+
`@example/my-schemas/types/foo`)
50
+
- `{{nsid}}` - the full NSID with dots replaced by slashes (e.g., `com/example/foo/bar`)
51
+
- `{{nsid_prefix}}` - the part before the wildcard (e.g., `com/example`)
52
+
- `{{nsid_remainder}}` - the part after the prefix (e.g., `foo/bar`)
27
53
28
54
## external references
29
55
30
56
when your lexicons reference types from namespaces outside your configured files, you'll need to
31
-
configure mappings to resolve these references.
57
+
configure how these references are resolved.
32
58
33
59
for example, if your lexicon references a type from another namespace:
34
60
···
54
80
}
55
81
```
56
82
57
-
define mappings in your configuration to specify how external namespaces should be imported:
83
+
the simplest way to resolve external references is using the `imports` array with packages that
84
+
provide the `atcute:lexicons` metadata:
85
+
86
+
```ts
87
+
// file: lex.config.js
88
+
import { defineLexiconConfig } from '@atcute/lex-cli';
89
+
90
+
export default defineLexiconConfig({
91
+
files: ['lexicons/**/*.json'],
92
+
outdir: 'src/lexicons/',
93
+
imports: ['@atcute/atproto', '@atcute/bluesky'],
94
+
});
95
+
```
96
+
97
+
the CLI will automatically discover the namespace mappings from each package's `atcute:lexicons`
98
+
field in their package.json.
99
+
100
+
for packages without metadata, or when you need more fine-grained control over import resolution,
101
+
use the `mappings` configuration instead:
58
102
59
103
```ts
60
104
// file: lex.config.js
···
81
125
],
82
126
});
83
127
```
84
-
85
-
with this configuration, any reference to a lexicon in the `com.atproto.*` or `app.bsky.*` namespace
86
-
will be imported from `@atcute/atproto` or `@atcute/bluesky`, respectively.