> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```ts theme={null}
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()](/typescript/markers-and-text) page).

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

<Note>
  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.
</Note>

## 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:

```ts theme={null}
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:

```ts theme={null}
// ❌ 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:

```ts theme={null}
AUTH.auth.login.valid
```

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

```ts theme={null}
AUTH["auth"]["login"]["valid"]
AUTH["multi-word-section"]
```

Dot and bracket accesses can be freely mixed:

```ts theme={null}
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.

<Tip>
  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.
</Tip>

## 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.