Importing xspec-Generated Modules into TypeScript

Learn how to import xspec-compiled spec modules into TypeScript, access nodes via dot and bracket notation, and use type-only imports.

After running xspec build, each NAME.mdx specification file is compiled into a typed TypeScript module that you can import directly into your source code. These generated modules expose a structured graph of your requirements as opaque, fully typed tokens — giving you editor autocomplete, hover documentation, and go-to-definition on every requirement node.

Basic import syntax

Import a compiled spec module using a specifier that mirrors the source .mdx path with the extension replaced by .xspec:

import AUTH, { text } from "../specs/AUTH.xspec"

Two bindings are permitted:

• Default export — the root node of the spec. All child sections are accessible as typed properties on this object.
• Named text export — a function for retrieving a node’s requirement text at runtime (covered in detail on the Markers & text() page).

Both bindings can be aliased and are independently optional. You may import one without the other.

The specifier must be a relative path ending in .xspec. It must not point to the generated implementation files directly — importing ./AUTH.xspec.ts, ./AUTH.xspec.impl.js, or similar underlying filenames is not supported and will be treated as an error by the xspec toolchain.

Type-only imports

If you only need to reference the spec’s types — for example in a typeof expression or a type annotation — you can use a type-only import:

import type AUTH from "../specs/AUTH.xspec"

Type-only imports are fully supported. Because they carry no value-level binding, xspec records no edges for them. They are useful when you want type safety without affecting the dependency graph.

Invalid import forms

The following import patterns are not permitted and will be flagged as build errors:

// ❌ Dynamic import
import("./AUTH.xspec")

// ❌ Re-export forms
export { default } from "./AUTH.xspec"
export * from "./AUTH.xspec"

// ❌ CommonJS-style require
import AUTH = require("./AUTH.xspec")

// ❌ Importing the generated implementation files directly
import AUTH from "./AUTH.xspec.ts"
import AUTH from "./AUTH.xspec.impl.js"

Only static import declarations using .xspec specifiers are valid.

Accessing nodes

The default export is the root node of the spec. Child sections defined by <S> headings in the source MDX are exposed as readonly typed properties, forming a path that mirrors your document’s heading hierarchy.

Use dot notation for identifier-safe segment names:

AUTH.auth.login.valid

Use bracket notation with string literals for segments that are not valid JavaScript identifiers:

AUTH["auth"]["login"]["valid"]
AUTH["multi-word-section"]

Dot and bracket accesses can be freely mixed:

AUTH.auth["login"].valid

Accessing a path that does not exist in the spec, or misspelling a segment name, produces a TypeScript type error at the point of access. The spec structure is fully reflected in the generated types, so your editor’s type checker enforces correctness without any runtime validation.

Nodes carry no text as values — you cannot read requirement content directly from a node expression. Use text(node) to retrieve the requirement text as a string at runtime.

Hover documentation and go-to-definition

Every node has a JSDoc comment attached to its type that contains the requirement’s own text (truncated to 1000 characters). When you hover over a node expression in a compatible editor such as VS Code, you will see the requirement text inline — without leaving your implementation file.

Go-to-definition on a node jumps directly to the corresponding <S> section in the .mdx source file, via the declaration map emitted alongside the generated types. This works out of the box with any editor that supports TypeScript’s language server and source maps.