Land
	Dependency 🖇️		Cargo 📦 Land 🏞️
	Dependency 🖇️ Land 🏞️		NPM 📦 Land 🏞️
	Echo 📣		Land 🏞️
	Editor 🏞️		Element 🌱
	Mountain ⛰️		River 🌊
	Sky 🌌		Sun ☀️
		Wind 🍃

Welcome to Land! We are building a high-performance, resource-efficient, and cross-platform code editor inspired by the architecture of VS Code, but re-imagined with a modern, declarative, and type-safe stack. Land is engineered with Rust and Tauri for the native backend (Mountain) and TypeScript with Effect-TS for all application logic (Wind and Cocoon).

Our vision is to deliver a lightning-fast and deeply reliable editing experience by leveraging declarative, effects-based programming across the entire application. This architecture ensures that all side effects—from filesystem operations to UI updates and network requests—are handled in a structured, testable, and composable way.

• Declarative Effect System: The entire application, from the Rust backend to the TypeScript frontend, is built on an effects-based architecture. We use a custom ActionEffect system in Rust and Effect-TS in TypeScript. This provides compile-time guarantees for error handling, resource management, and asynchronicity, leading to exceptional stability.
• High-Performance Backend: The Mountain backend is written in Rust, providing native speed for all core operations like file I/O, search, and process management.
• High-Fidelity Extension Host: The Cocoon sidecar is a Node.js process designed to run existing VS Code extensions with high compatibility. It provides a sandboxed vscode API, built with Effect-TS, that communicates with Mountain for all native operations.
• Modern UI Services: The Wind project is a from-scratch, Effect-TS native re-implementation of the VS Code workbench services, providing a clean, functional, and testable foundation for the UI.
• Strongly-Typed IPC: All communication between the Mountain backend and the Cocoon extension host is handled via gRPC, ensuring a robust, performant, and strongly-typed API contract defined in a .proto file.

Land's architecture is composed of several key components that work in concert to deliver a modern editing experience.

To understand how these components interact, please refer to the detailed workflow descriptions in docs/Workflow.md. The following provides a table of contents for these essential processes.

1. Application Startup & Handshake

   • Describes the complete end-to-end process of launching Mountain, spawning Cocoon, and establishing a stable, initialized state for both the UI and the extension host.

2. Opening a File from the UI

   • Details the flow from a user clicking a file in the explorer to the content being read from disk by Mountain and rendered in an editor by Wind.

3. Invoking a Language Feature (Hover Provider)

   • A key example of bi-directional communication, showing how an extension in Cocoon registers a feature, Mountain orchestrates the request, and the result is displayed in the Wind UI.

4. Saving a File with Save Participants

   • Explains the advanced process of intercepting a save event, allowing an extension in Cocoon to modify a file (e.g., for formatting) before Mountain writes it to disk.

5. Executing a Command from the Command Palette

   • Illustrates the unified command system, showing how Mountain's command registry can seamlessly dispatch execution to either a native Rust handler or a proxied command in Cocoon.

6. Creating and Interacting with a Webview Panel

   • Details the full lifecycle of extension-contributed UI, from Cocoon requesting a panel to Mountain managing the native webview window and proxying messages back and forth.

7. Creating and Interacting with an Integrated Terminal

   • A deep dive into native process management, showing how Mountain spawns a PTY process and streams its I/O to both the Wind frontend and the Cocoon extension host.

8. Source Control Management (SCM)

   • Outlines how the built-in Git extension in Cocoon uses Mountain as a service to run native git commands and then populates the SCM view in the UI with the results.

9. User Data Synchronization

   • Describes the end-to-end process of syncing user settings. It covers user authentication, fetching data from a remote store, performing a three-way merge, applying changes locally, and notifying all parts of the application.

10. Running Extension Tests

    • Explains the "Extension Development Host" model, where a second, isolated instance of the application is launched to run tests, with the test Cocoon instance remote-controlling the main UI.

The following workflows are implemented in the codebase but are pending detailed documentation.

• Tree View Data Flow
• Custom Editor Lifecycle
• Debugging Session Lifecycle
• Task Execution

While Cocoon provides high compatibility with the existing VS Code ecosystem, our long-term vision includes Grove, a native Rust extension host. Grove aims to provide a highly optimized, secure, and performant environment for extensions written in Rust or compiled to WASM, drastically reducing the overhead of a Node.js runtime and enabling deeper integration with Mountain.

Our codebase is organized into "Elements", each representing a distinct component or library with a clear purpose. Most Elements are managed as Git submodules within the main Land repository, allowing for independent development and versioning.

This diagram illustrates the build-time and runtime interactions between the primary components of the Land application.

graph LR
    classDef mountain fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cocoon fill:#ccf,stroke:#333,stroke-width:2px;
    classDef wind fill:#9cf,stroke:#333,stroke-width:2px;
    classDef common fill:#cfc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ipc fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef build fill:#ddd,stroke:#666;
    classDef data fill:#eee,stroke:#666;

    subgraph "Build Time Process"
        direction LR
        VSCodeSource["VS Code Source (Dependency/Editor)"]:::build
        RestBuild["JS Bundler (Rest Element)"]:::build
        CocoonBundleJS(Cocoon Runtime JS):::data
        SkyBuildProcess["Sky Build (Sky Element)"]:::build
        SkyAssets(Sky Frontend Assets):::data

        VSCodeSource --> RestBuild;
        VSCodeSource -- Uses UI code --> SkyBuildProcess;
        RestBuild --> CocoonBundleJS;
        SkyBuildProcess --> SkyAssets;
    end

    subgraph "Runtime: **Land** Application"
        subgraph "Native Backend (Rust)"
            Mountain["**Mountain (Tauri App)**"]:::mountain
            CommonCrate[**Common Crate**]:::common
            TrackDispatcher[Track Dispatcher]:::mountain
            VineGRPCServer[Vine gRPC Server]:::mountain
            NativeHandlers["Native Logic Handlers"]:::mountain
            ProcessMgmt["Process Management"]:::mountain

            Mountain -- Uses --> TrackDispatcher
            TrackDispatcher -- Routes to --> NativeHandlers
            Mountain -- Implements traits from --> CommonCrate
            Mountain -- Contains --> VineGRPCServer
            Mountain -- Contains --> ProcessMgmt
        end

        subgraph "UI Frontend (Tauri Webview)"
            WindServices["**Wind (Effect-TS Services)**"]:::wind
            SkyUI["**Sky (UI Components)**"]:::wind
            WindServices -- Drives state of --> SkyUI
        end

        subgraph "Extension Host (Node.js Sidecar)"
            Cocoon[**Cocoon Process**]:::cocoon
            VineGRPCClient[Vine gRPC Client]:::cocoon
            VSCodeAPI[vscode API Shim]:::cocoon
            Extension["Extension Code"]:::cocoon

            Cocoon -- Contains --> VineGRPCClient
            Cocoon -- Provides --> VSCodeAPI
            VSCodeAPI -- Used by --> Extension
        end

        ProcessMgmt -- Spawns & Manages --> Cocoon

        WindServices -- Tauri IPC (Commands & Events) --> TrackDispatcher
        VineGRPCClient -- gRPC (Vine Protocol) <--> VineGRPCServer; class VineGRPCClient,VineGRPCServer ipc;

    end

    CocoonBundleJS -- Loaded by --> Cocoon;
    SkyAssets -- Loaded by --> WindServices;

Follow these steps to get Land up and running on your system.

This command downloads the Land project files. The --recurse-submodules flag is crucial as it fetches all "Element" submodules and the VS Code source code dependency.

git clone ssh://git@github.com/CodeEditorLand/Land.git --recurse-submodules

This command uses pnpm (a Node.js package manager) to install all JavaScript dependencies required for building the Sky frontend, the Cocoon sidecar, and various development tools.

pnpm install

The build process is multi-stage. It uses a set of environment variables to control the output, allowing you to create either an optimized production build or a flexible development build.

Build Variables Explained:

These variables are passed to our build scripts to configure their behavior:

Development Build:

This command creates a full development build of the application. The output is not as optimized as a release build but is ideal for debugging.

pnpm cross-env \
	NODE_ENV=development \
	Clean=true \
	Browser=true \
	Dependency=Microsoft/VSCode \
	Bundle=false \
	Compile=false \
	NODE_OPTIONS=--max-old-space-size=16384 \
	pnpm tauri build

Production Build (Release):

This command creates a fully optimized, minified, and production-ready version of Land, suitable for packaging and distribution.

pnpm cross-env \
	NODE_ENV=production \
	Clean=true \
	Browser=true \
	Dependency=Microsoft/VSCode \
	Bundle=true \
	Compile=true \
	NODE_OPTIONS=--max-old-space-size=16384 \
	pnpm tauri build --release

This is the primary command you will use during active development. It starts Land with hot-reloading enabled for the frontend, allowing UI changes to be seen instantly without a full application rebuild.

Notice that Bundle and Compile are set to false. This is because tauri dev uses Vite (or a similar dev server) which handles module bundling on-the-fly, providing a much faster development experience.

pnpm cross-env \
	NODE_ENV=development \
	Clean=true \
	Browser=true \
	Dependency=Microsoft/VSCode \
	Bundle=false \
	Compile=false \
	NODE_OPTIONS=--max-old-space-size=16384 \
	pnpm tauri dev

This project is released into the public domain under the Creative Commons CC0 Universal license. You are free to use, modify, distribute, and build upon this work for any purpose, without any restrictions. For the full legal text, see the LICENSE file.

Stay updated with our progress! See CHANGELOG.md for a history of changes.

Land 🏞️ is proud to be an open-source endeavor. Our journey is significantly supported by the organizations and projects that believe in the future of open-source software.

This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Land	PlayForm	NLnet	NGI0 Commons Fund

This project would not be possible without the incredible work of the open-source community. We are especially grateful for the following foundational technologies and projects:

• Tauri: For providing a secure, performant, and resource-efficient framework for building our native desktop application with a web frontend.
• Microsoft Visual Studio Code: For open-sourcing their workbench UI and platform code, which provides the foundation for our user interface and extension host compatibility.
• Effect-TS: For enabling us to build a robust, type-safe, and declarative application with a powerful structured concurrency and dependency management system in TypeScript.
• Rust: For the performance, safety, and modern tooling that powers our entire native backend.
• Tokio & Tonic: For providing the asynchronous runtime and gRPC framework that are the backbone of our high-performance IPC.
• Astro: For its content-driven approach that allows us to build a fast and modern user interface for the Sky component.
• PNPM: For efficient and reliable management of our JavaScript dependencies.
• and many many more...

We extend our sincere gratitude to the maintainers and contributors of these and all the other dependencies we use. ❤️

Project Maintainers: Source Open (Source/Open@Editor.Land) | GitHub Repository | Report an Issue | Security Policy