langium
A comprehensive skill to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration
eclipse-langium · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add eclipse-langium/langium-ai --skill langiumAbout this skill
name: langium description: A comprehensive skill to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration user-invocable: false
Langium SKILL.md
A comprehensive guide to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration. Reading this document should make an agent fully proficient at navigating, debugging, and extending any Langium DSL project.
Table of Contents
- High-Level Architecture
- The Grammar Language
- Code Generation (Build Time)
- Dependency Injection System
- Lexing
- Parsing: Tokens → CST → AST
- The Document Lifecycle (DocumentState Pipeline)
- Scope Computation
- Scope Provider and Name Resolution
- Linking and Cross-Reference Resolution
- Validation
- Workspace Management
- LSP Integration
- Common Customization Patterns
- End-to-End Runtime Flow
1. High-Level Architecture
Langium is a language engineering framework that takes a .langium grammar file and produces a fully operational TypeScript-based DSL toolkit with LSP support. The architecture has two major phases:
Build time — langium-cli reads .langium grammars and generates:
ast.ts— TypeScript interfaces for every AST node, type guards, and anAstReflectionclassgrammar.ts— The grammar serialized as JSON, lazy-loaded at runtimemodule.ts— A DI module providingGrammar,LanguageMetaData, andAstReflectionservices
Runtime — A service-oriented architecture driven by dependency injection:
- All components (parser, lexer, linker, scope provider, validator, LSP handlers) are registered as services
- Two service layers: shared services (cross-language: workspace, index, document management) and language-specific services (parser, references, validation — one set per language)
- Users customize behavior by providing partial DI modules that override default service factories
Key dependency: Chevrotain (parser generator library) powers the lexer and parser at runtime.
2. The Grammar Language
A .langium file defines the DSL's syntax and implicitly its AST structure. Key constructs:
Parser Rules
// entry rule — the root of the AST
entry Model:
(elements+=Element)*;
// regular rule — creates an AST node of type 'Element'
Element:
'element' name=ID '{' attributes+=Attribute* '}';
entrymarks the grammar's starting rule (one per grammar)- Assignments:
=(single value),+=(array append),?=(boolean flag) name=IDassigns the matched ID terminal to thenameproperty
Cross-References
Reference:
'ref' target=[Element:ID] ';';
[Element:ID]— references anElementnode by matching theIDterminal- At parse time, creates a lazy
Referenceobject with$refTextset to the matched text - At link time, the
ScopeProviderresolves the text to the actual target node
Actions (Type Changing)
Expression:
Primary ({BinaryExpression.left=current} operator=('+' | '-') right=Primary)*;
{BinaryExpression.left=current}creates a newBinaryExpressionnode, assigning the previously parsed node to itsleftproperty- Enables left-recursive expression patterns
Infix Rules
infix Expression:
Primary
('+' | '-') // precedence 0 (lowest)
('*' | '/') // precedence 1
('**' right-assoc); // precedence 2, right-associative
- Declarative operator precedence and associativity
- Operators listed top-to-bottom from lowest to highest precedence
Terminal Rules
terminal ID: /[_a-zA-Z][\w_]*/;
terminal STRING: /"(\\.|[^"\\])*"|'(\\.|[^'\\])*'/;
hidden terminal WS: /\s+/;
hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
hiddenterminals (whitespace, comments) are excluded from the main token stream- Terminal order affects lexer priority; keywords always take precedence over terminals
Fragment Rules
fragment NamedElement:
name=ID;
- Fragments contribute properties to the calling rule's AST node without creating a new node type
Type Declarations
interface Declaration {
name: string
}
type Literal = StringLiteral | NumberLiteral;
- Explicit AST type declarations (alternative to grammar-inferred types)
returns/inferskeywords control which type a parser rule produces
Imports
import './other-grammar'
- Multi-file grammars with shared rules and types
3. Code Generation (Build Time)
The langium-cli generates three files from each grammar. Understanding what's generated is critical to understanding the runtime.
3.1 ast.ts — AST Type Definitions
For each grammar rule/type, generates:
TypeScript interface:
export interface Element extends langium.AstNode {
readonly $type: "Element";
name: string;
attributes: Array<Attribute>;
}
Const object (property name literals):
export const Element = {
$type: "Element",
name: "name",
attributes: "attributes",
} as const;
Type guard:
export function isElement(item: unknown): item is Element {
return reflection.isInstance(item, Element.$type);
}
Terminal regexes and keyword types:
export const MyLangTerminals = {
ID: /[_a-zA-Z][\w_]*/,
STRING: /
Read the complete source ↗