---
sidebar_position: 2
title: Getting Started
---

# Getting Started: Hello World

Let's write a minimal OSUI application that displays "Hello World" in the terminal. This example will introduce you to the core concepts of an OSUI application: the `Console` engine, running an application, and defining a basic component with `rsx!`.

## 1. Create a New Project

If you haven't already, create a new Rust binary project:

```bash
cargo new hello-osui
cd hello-osui
```

## 2. Add OSUI Dependency

```bash
cargo add osui
```

## 3. Write the Hello World Code

Open `src/main.rs` and replace its contents with the following:

```rust title="src/main.rs"
use osui::prelude::*; // Import commonly used OSUI items
use std::sync::Arc;

pub fn main() {
    // 1. Initialize the Console engine
    // The Console engine uses crossterm to interact with the terminal.
    let engine = Console::new();

    // 2. Run the application
    // The `run` method takes your root component and starts the rendering loop.
    // It returns a `Result`, which we unwrap here for simplicity.
    engine.run(App {}).expect("Failed to run OSUI application");
}

/// 3. Define your root component
/// The `#[component]` attribute transforms a function into a reusable UI component.
/// - The first parameter `cx: &Arc<Context>` is mandatory and provides access to component context (state, events, children).
/// - Components must return a `View`.
#[component]
fn App(cx: &Arc<Context>) -> View {
    // 4. Use RSX (React-like Syntax) to define the UI
    // `rsx!` is a procedural macro for declarative UI construction.
    // Here, it just renders a simple string literal.
    rsx! {
        "Hello World"
    }
    // `view(&cx)` converts the RSX into a `View` that can be rendered.
    .view(&cx)
}
```

## 4. Run Your Application

Execute your application from the terminal:

```bash
cargo run
```

You should see "Hello World" displayed in your terminal, which will then clear when the application exits.

## Understanding the Code

Let's break down the key parts of the "Hello World" example:

*   **`use osui::prelude::*;`**: This line imports the `prelude` module, which re-exports the most commonly used types and macros from OSUI. This includes `Console`, `Context`, `View`, `#[component]`, and `rsx!`.
*   **`Console::new()`**: The `Console` struct is OSUI's default rendering engine. It uses the `crossterm` library to draw content to your terminal.
*   **`engine.run(App {})`**: This starts the OSUI application lifecycle. It takes an instance of your root component (`App {}` in this case) and begins the continuous rendering loop. The `App` component will be rendered repeatedly until the application is stopped (e.g., by pressing `Ctrl+C` or a command from within the app).
*   **`#[component] fn App(cx: &Arc<Context>) -> View { ... }`**:
    *   The `#[component]` attribute is a procedural macro that transforms a standard Rust function into an OSUI component. This enables prop handling and integration into the component tree.
    *   All component functions must take `cx: &Arc<Context>` as their first argument. The `Context` provides access to component-specific state, lifecycle methods, event handlers, and the ability to add child components.
    *   Component functions must return a `View`, which is an `Arc<dyn Fn(&mut DrawContext) + Send + Sync>`. This `View` represents the instructions for rendering the component.
*   **`rsx! { "Hello World" }.view(&cx)`**:
    *   The `rsx!` macro is OSUI's declarative UI syntax. It allows you to define a hierarchy of components and text nodes in a way that feels similar to HTML or React's JSX.
    *   In this simple case, `"Hello World"` is a text literal that `rsx!` converts into a renderable element.
    *   The `.view(&cx)` method takes the `Rsx` object generated by the `rsx!` macro and processes it within the current `Context`, ultimately producing the final `View` to be returned by the component.

This simple example demonstrates the fundamental building blocks of an OSUI application. Next, we'll explore how to create more complex components and pass data between them.

**Next:** Learn about [Creating Components](./03-example-basic-component.md) and passing them data.