DOCSEARCHbyAlgolia
Submit Docs

Imba Documentation

repository·main·Indexed 27 days ago

https://github.com/imba/imba

Documentation for Imba and Imba Next, featuring a next-generation language server and TypeScript plugin for VS Code. Includes guides on integrated styling with CSS blocks, importing workers and images, and using TypeScript types. Covers the imba-language-core Volar plugin, imba-language-server, and imba-typescript-plugin for high-fidelity development experiences, as well as the convert-css CLI tool.

Tokens
70.7K
Snippets
255
Records
560
Agent score
92%

What's inside Imba

  2. Overview of imba-typescript-plugin

    main

    The imba-typescript-plugin is a next-generation tsserver plugin for Imba, built on @volar/typescript. It is the successor to typescript-imba-plugin.

    It enables plain TypeScript/JavaScript projects to become aware of .imba files by providing:

    • Module resolution for Imba files
    • Cross-file type support
    • Rename support
    • Auto-import functionality

    It achieves this by registering the imba-language-core language plugin through Volar's maintained tsserver integration without monkey-patching tsserver internals.

  3. Overview of imba-language-core

    main
    imba-language-core is a Volar LanguagePlugin for Imba. It serves as the foundation for next-generation Imba tooling by transforming .imba files into virtual TypeScript documents. It uses the imba compiler's tsc target to produce JavaScript, location data, and diagnostics, which are then mapped to Volar CodeMappings. This allows Volar to handle coordinate translation for diagnostics, hover, navigation, rename, and completions in both the language server and tsserver plugin modes.

  6. Understand Imba's Declarative Rendering

    main
    Unlike frameworks that use a Virtual DOM to diff lightweight representations, Imba works with real DOM nodes. When render() is called, Imba directly modifies the real DOM elements to match the declared state. This approach is designed to be orders of magnitude faster than Virtual DOM reconciliation because it performs minimal, direct updates to the actual elements.

  7. Features available in Imba Next (Preview)

    main

    The Imba Next preview provides the following language tooling capabilities:

    • Live diagnostics: Real-time Imba parse errors and TypeScript noise filtered by Imba forgiveness rules.
    • Navigation: Hover, go to definition, find references, and rename functionality working both within .imba files and across the TypeScript/Imba boundary.
    • Code Intelligence: Semantic highlighting, outline/breadcrumbs (via the monarch parser), and TS-backed completions at mapped positions.
    • Module Resolution: Support for extensionless imports, .web.imba imports, and resolving imba to the real stdlib types.

  8. Understand CSS syntax definitions in syntaxes.json

    main

    The syntaxes.json file (sourced from MDN data) defines the formal syntax for CSS properties. Syntaxes are expressed using a grammar that can include:

    • Keywords: Separated by a pipe (|), e.g., scroll | fixed | local.
    • CSS Types: References to standard CSS types, e.g., <number> | <percentage>.
    • Nested Syntaxes: References to other syntax definitions within the same file, e.g., a shape-radius syntax referencing a length-percentage syntax.

    Property definitions in properties.json link to these syntaxes using the <name> notation, often followed by a # to indicate repetition.

  10. Install and use the Imba VSCode Plugin

    main

    The Imba VSCode Plugin provides essential development features for Imba, including syntax highlighting, intellisense, go to definition, and hinting.

    Requirement: This extension requires TypeScript 5.x.

    Important Configuration Note: If you have previously configured the typescript.tsdk setting to use an older version of TypeScript for a previous version of this extension, you must remove that setting to ensure compatibility with TypeScript 5.x.

  11. Understand the Imba Field Registry

    main

    The Imba compiler can emit a type-only registry for class field declarations that use decorator-style field descriptors (e.g., @embed(Variant)). This is a framework-agnostic feature that provides syntactic and type facts that libraries can interpret in TypeScript.

    Key Characteristics:

    • Type-only: The output is for declarations/types and has no runtime effect.
    • Opaque Keys: Registry keys start with _$INTERNAL$_ to allow tooling to hide them while still allowing helper types to filter by prefix.
    • Inverse Lookup: The registry enables finding which owner classes and fields point to a specific target type via a hidden, optional, readonly property on the target interface.

  12. Use conditionals and loops in templates

    main

    Since tag trees are code, you can use standard control flow statements like if/else and for loops directly within your templates.

    Conditionals

    <div>
    if items
        <h1> "List of items:"
    else
        <span> "No items found"

    Loops

    <ul for item in items
    <li> <span> item

    You can also use break and continue within loops.

    <div>
    if items
        <h1> "List of items:"
        <ul for item in items
            <li> <span> item
    else
        <span> "No items found"