### Start HeliumTS Development Server

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Starts the HeliumTS development server using the `helium dev` command. This command will build and serve the application, allowing for live development.

```bash
npx helium dev
```

--------------------------------

### Create Basic Project Structure

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Sets up the initial directory structure for the application, including `src/pages` and `src/server`. This structure is standard for HeliumTS applications.

```bash
mkdir -p src/pages src/server
```

--------------------------------

### TypeScript Example: Full Helium Configuration

Source: https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md

A comprehensive TypeScript example demonstrating the HeliumConfig structure, including proxy trust depth, RPC transport modes, compression settings, and security parameters like connection limits and message rates. This configuration is suitable for production environments.

```typescript
import type { HeliumConfig } from "heliumts/server";

const config: HeliumConfig = {
    // Trust 1 proxy level (e.g., Vercel)
    trustProxyDepth: 1,

    // RPC configuration
    rpc: {
        // Client-side transport mode
        transport: "websocket",    // Default: WebSocket for lowest latency
        autoHttpOnMobile: false,   // Set to true to optimize for mobile networks

        // Enable compression for messages over 1KB
        compression: {
            enabled: true,
            threshold: 1024,
        },

        // Security and rate limiting
        security: {
            maxConnectionsPerIP: 10,
            maxMessagesPerWindow: 100,
            rateLimitWindowMs: 60000,
            tokenValidityMs: 30000,
        },
    },
};

export default config;
```

--------------------------------

### Basic Helium Configuration Setup (TypeScript)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md

Demonstrates the fundamental structure for creating a Helium configuration file (`helium.config.ts`). It imports the necessary type and exports a default configuration object.

```typescript
import type { HeliumConfig } from "heliumts/server";

const config: HeliumConfig = {
    // Your configuration here
};

export default config;
```

--------------------------------

### Docker Deployment Configuration

Source: https://github.com/heliobentes/heliumts/blob/main/docs/production-deployment.md

This Dockerfile outlines the steps to containerize a Helium application for production deployment. It installs dependencies, copies the built application files, exposes the application port, and defines the command to run the server. This setup is suitable for container orchestration platforms or self-hosted Docker environments.

```dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci --only=production

# Copy built files
COPY dist ./dist

# The config file should be in dist/ after build
EXPOSE 3000

CMD ["node", "dist/server.js"]
```

--------------------------------

### Create First Page Component

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Creates a simple `index.tsx` file within the `src/pages` directory to serve as the application's homepage. This demonstrates how to create a basic page component.

```tsx
import React from "react";

export default function HomePage() {
    return (
        <div>
            <h1>Welcome to HeliumTS</h1>
            <p>Start building your app!</p>
        </div>
    );
}
```

--------------------------------

### Install HeliumTS Package

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Installs the HeliumTS package into the project. This is a crucial step to integrate HeliumTS functionalities into your application.

```bash
npm install heliumts
```

--------------------------------

### Create React + Vite Project

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Initializes a new Vite project with the React TypeScript template. This command sets up the basic project structure and dependencies for a React application using Vite as the build tool.

```bash
npm create vite@latest my-helium-app -- --template react-ts
cd my-helium-app
```

--------------------------------

### Build Failure Example (Text)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md

Displays an example of a build failure due to a rendering timeout, generating a fallback HTML file.

```text
  ✗ pages/problematic.tsx - Rendering timeout after 10000ms - page may contain hooks or async operations
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

This command installs all the necessary project dependencies defined in the `package.json` file using npm. Ensure you have Node.js and npm installed.

```bash
npm install
```

--------------------------------

### JavaScript Example: Manual Configuration File

Source: https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md

A JavaScript configuration object intended for use with `helium.config.js`. This demonstrates the structure for `trustProxyDepth`, RPC compression, and security settings, mirroring the TypeScript configuration but using plain JavaScript syntax.

```javascript
// helium.config.js
export default {
    trustProxyDepth: 1,
    rpc: {
        compression: {
            enabled: true,
            threshold: 1024,
        },
        security: {
            maxConnectionsPerIP: 10,
            maxMessagesPerWindow: 100,
            rateLimitWindowMs: 60000,
            tokenValidityMs: 30000,
        },
    },
};
```

--------------------------------

### TypeScript Example: Environment-Specific Configuration

Source: https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md

Illustrates how to dynamically configure Helium TS based on the environment (development or production) using environment variables. It adjusts `trustProxyDepth` and RPC security settings to optimize performance and security for different deployment stages.

```typescript
import type { HeliumConfig } from "heliumts/server";

const isDevelopment = process.env.NODE_ENV === "development";
const isProduction = process.env.NODE_ENV === "production";

const config: HeliumConfig = {
    trustProxyDepth: isProduction ? 1 : 0,

    rpc: {
        compression: {
            enabled: isProduction,
            threshold: 1024,
        },

        security: {
            maxConnectionsPerIP: isDevelopment ? 100 : 10,
            maxMessagesPerWindow: isDevelopment ? 1000 : 100,
            rateLimitWindowMs: 60000,
            tokenValidityMs: 30000,
        },
    },
};

export default config;
```

--------------------------------

### Build Output Example (Text)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md

Shows typical build output during SSG, indicating the number of static pages generated and their sizes.

```text
Generating 3 static page(s) for SSG...
  index.html                               2.45 kB │ gzip:    1.12 kB
  about.html                               3.21 kB │ gzip:    1.54 kB
  contact.html                             2.87 kB │ gzip:    1.33 kB
```

--------------------------------

### Fetch Blog Post Data with Dynamic Routes in HeliumTS

Source: https://github.com/heliobentes/heliumts/blob/main/docs/routing.md

This example shows how to create a dynamic blog post page using HeliumTS. It utilizes `useRouter` to get the dynamic `slug` from the URL and `useFetch` hook (from 'heliumts/client') to asynchronously fetch the blog post data using a server function `getBlogPost` (from 'heliumts/server').

```tsx
// src/pages/blog/[slug].tsx
import { useRouter } from "heliumts/client";
import { useFetch } from "heliumts/client";
import { getBlogPost } from "heliumts/server";

export default function BlogPostPage() {
    const router = useRouter();
    const slug = router.params.slug as string;

    const { data: post, isLoading } = useFetch(getBlogPost, { slug });

    if (isLoading) return <div>Loading...</div>;
    if (!post) return <div>Post not found</div>;

    return (
        <article>
            <h1>{post.title}</h1>
            <div>{post.content}</div>
        </article>
    );
}

```

--------------------------------

### Build and Start Helium Production Server

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

Builds the HeliumTS project for production and then starts the production server. Used for testing optimized builds, Server-Side Rendering (SSR), and configuration transpilation. Requires Node.js and the HeliumTS package.

```bash
npx helium build
npx helium start
```

--------------------------------

### Remove Vite's Main Entry Point

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Removes the default `main.tsx` file and its reference from `index.html`. HeliumTS manages the client entry point, so this file is not needed.

```html
<!-- Remove this from index.html -->
<script type="module" src="/src/main.tsx"></script>
```

--------------------------------

### Basic Static Page Example

Source: https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md

This example demonstrates a basic static page that can be generated using SSG. By including the 'use ssg' directive, the 'ContactPage' component will be pre-rendered into an HTML file (e.g., dist/contact.html) during the build. It's designed for content that remains constant.

```tsx
"use ssg";

export default function ContactPage() {
    return (
        <div>
            <h1>Contact Us</h1>
            <p>Email: hello@example.com</p>
        </div>
    );
}

```

--------------------------------

### Test Local HeliumTS Build in an Application

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

After building and packing your local HeliumTS changes, this command installs the generated `.tgz` file into a test application and starts the development server, allowing you to test your modifications in a real project environment.

```bash
cd ../test-app
npm install file:../heliumts/heliumts-0.0.0.tgz --force
npx helium dev
```

--------------------------------

### useFetch Hook: Conditional Data Fetching Example

Source: https://context7.com/heliobentes/heliumts/llms.txt

Shows how to use the `enabled` option in `useFetch` to perform data fetching only when a specific condition is met. This example fetches user search results only after the user has typed at least three characters into the input field.

```tsx
// src/pages/tasks.tsx (continued)
// Conditional fetching example
function UserSearch() {
    const [searchTerm, setSearchTerm] = useState("");
    const shouldSearch = searchTerm.length >= 3;

    const { data: users, isLoading } = useFetch(
        searchUsers,
        { query: searchTerm },
        { enabled: shouldSearch }  // Only fetch when user types 3+ chars
    );

    return (
        <div>
            <input
                value={searchTerm}
                onChange={e => setSearchTerm(e.target.value)}
                placeholder="Search users (min 3 chars)"
            />
            {isLoading && <span>Searching...</span>}
            {shouldSearch && users?.map(u => <div key={u.id}>{u.name}</div>)}
        </div>
    );
}
```

--------------------------------

### Create and Test Local HeliumTS Build

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

This sequence sets up a new React + Vite project, installs a locally built HeliumTS package, and then runs the Helium development server to verify the local build.

```bash
npm create vite@latest test-app -- --template react-ts
cd test-app

npm install ../helium-0.0.0.tgz

npx helium dev
```

--------------------------------

### GET Product by Category and ID (Dynamic Route)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Handles a dynamic route with multiple path parameters to retrieve specific product information.

```APIDOC
## GET /api/products/:category/:id

### Description
Fetches product details using both the product category and its unique ID from the URL path.

### Method
GET

### Endpoint
/api/products/:category/:id

### Parameters
#### Path Parameters
- **category** (string) - Required - The category of the product.
- **id** (string) - Required - The unique identifier for the product.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **category** (string) - The category of the product.
- **id** (string) - The unique identifier for the product.

#### Response Example
```json
{
  "category": "electronics",
  "id": "abc789"
}
```
```

--------------------------------

### Expose Client-Side Environment Variables in Helium

Source: https://github.com/heliobentes/heliumts/blob/main/docs/production-deployment.md

This section shows how to expose environment variables to the browser by prefixing them with `HELIUM_PUBLIC_`. It includes examples of setting these variables in `.env` files or platform environments and accessing them in React components using `import.meta.env`. Note that these variables are injected at build time.

```bash
# .env or platform environment variables
HELIUM_PUBLIC_APP_NAME=My App
HELIUM_PUBLIC_API_URL=https://api.example.com
HELIUM_PUBLIC_FEATURE_FLAG=true
```

```typescript
function MyComponent() {
    const appName = import.meta.env.HELIUM_PUBLIC_APP_NAME;
    const apiUrl = import.meta.env.HELIUM_PUBLIC_API_URL;
    const featureEnabled = import.meta.env.HELIUM_PUBLIC_FEATURE_FLAG === 'true';
    
    return <div>{appName} - {apiUrl}</div>;
}
```

--------------------------------

### Error Handling: Missing RPC Configuration

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

Demonstrates correct and incorrect ways to throw an error when crucial configuration, like RPC settings, is missing. The good example provides a descriptive error message, while the avoided example uses a vague message.

```typescript
// ✅ Good
if (!config.rpc) {
    throw new Error("RPC configuration is missing in helium.config.ts");
}

// ❌ Avoid
if (!config.rpc) {
    throw new Error("Missing config");
}
```

--------------------------------

### Clone and Setup Upstream Repository

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

This bash script demonstrates how to fork the HeliumTS repository, clone your fork locally, and add the original repository as an upstream remote for future synchronization.

```bash
git clone https://github.com/YOUR_USERNAME/heliumts.git
cd heliumts

git remote add upstream https://github.com/heliobentes/heliumts.git
```

--------------------------------

### Implementing Logging and Analytics

Source: https://github.com/heliobentes/heliumts/blob/main/docs/context-api.md

An example RPC method designed for logging and analytics. It captures event details, client IP, user agent, and timestamp from the context and arguments to log an event.

```typescript
export const trackEvent = defineMethod(async (args, ctx) => {
    await logEvent({
        event: args.eventName,
        ip: ctx.req.ip,
        userAgent: ctx.req.headers["user-agent"],
        timestamp: Date.now(),
    });

    return { tracked: true };
});
```

--------------------------------

### POST /api/resource

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

An example endpoint demonstrating various HTTP status codes for different scenarios like creation, bad requests, not found, and unauthorized access.

```APIDOC
## POST /api/resource

### Description
Handles resource creation and demonstrates various status codes based on the request body and server state.

### Method
POST

### Endpoint
/api/resource

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **action** (string) - Optional - The action to perform (e.g., 'create').
- **email** (string) - Required - The email address for the resource.
- **id** (string) - Optional - The ID of the resource.

### Request Example
```json
{
  "action": "create",
  "email": "test@example.com"
}
```

### Response
#### Success Response (200, 201)
- **id** (string) - The ID of the created resource (201).
- **success** (boolean) - Indicates success (200).

#### Error Responses
- **400 Bad Request**: If required data like 'email' is missing.
- **401 Unauthorized**: If the user is not authenticated.
- **404 Not Found**: If a specified resource does not exist.

#### Response Example (Success - 201)
```json
{
  "id": "123"
}
```

#### Response Example (Error - 400)
```json
{
  "error": "Email required"
}
```
```

--------------------------------

### Basic GET Endpoint

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Defines a simple GET endpoint that returns a JSON message. This is a fundamental example for creating custom HTTP handlers.

```APIDOC
## GET /api/hello

### Description
Creates a basic GET endpoint that responds with a "Hello World" message.

### Method
GET

### Endpoint
/api/hello

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - A greeting message.

#### Response Example
```json
{
  "message": "Hello World"
}
```
```

--------------------------------

### GET User by ID (Dynamic Route)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

An example of a dynamic route that captures a user ID from the URL path and fetches user data.

```APIDOC
## GET /api/users/:id

### Description
Retrieves a user based on their unique ID provided in the URL path.

### Method
GET

### Endpoint
/api/users/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the user.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **user** (object) - An object containing the user's data.

#### Response Example
```json
{
  "user": {
    "id": "123",
    "name": "John Doe"
  }
}
```
```

--------------------------------

### Update App Component for HeliumTS

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Replaces the content of `src/App.tsx` to use HeliumTS's `AppShellProps`. This component serves as the main shell for your HeliumTS application.

```tsx
import { type AppShellProps } from "heliumts/client";

export default function App({ Component, pageProps }: AppShellProps) {
    return <Component {...pageProps} />;
}
```

--------------------------------

### Initialize AppRouter Context

Source: https://github.com/heliobentes/heliumts/blob/main/docs/routing.md

This example demonstrates the correct way to set up the AppRouter context, which is necessary for hooks like useRouter to function correctly. Ensure your root application file (e.g., src/main.tsx) wraps your application's components with <AppRouter>.

```tsx
// src/main.tsx
import { AppRouter } from "heliumts/client";

ReactDOM.createRoot(document.getElementById("root")!).render(<AppRouter>{/* Your app */}</AppRouter>);

```

--------------------------------

### Configure Vite with HeliumTS Plugin

Source: https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md

Updates the `vite.config.ts` file to include the HeliumTS Vite plugin. This plugin is necessary for HeliumTS to work correctly with Vite's build process.

```typescript
import react from '@vitejs/plugin-react';
import helium from 'heliumts/vite';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [react(), helium()]
});
```

--------------------------------

### Type Route Parameters with TypeScript

Source: https://github.com/heliobentes/heliumts/blob/main/docs/routing.md

This example demonstrates how to strongly type route parameters using TypeScript with heliumts/client. Define an interface for your parameters and cast router.params to this type to get type safety for your dynamic route segments.

```tsx
import { useRouter } from "heliumts/client";

type UserPageParams = {
    id: string;
};

export default function UserPage() {
    const router = useRouter();
    const { id } = router.params as UserPageParams;

    // id is typed as string
    return <div>User: {id}</div>;
}

```

--------------------------------

### Hybrid Rendering Example (TypeScript)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md

Shows a hybrid rendering approach where a page is rendered statically at build time and then hydrates on the client to fetch dynamic data using `useState` and `useEffect`.

```tsx
"use ssg";

import { useState, useEffect } from "react";

export default function HybridPage() {
    const [clientData, setClientData] = useState<string | null>(null);

    // Static content rendered at build time
    const staticContent = "This is static content";

    // Dynamic content loaded on the client
    useEffect(() => {
        fetch("/api/data")
            .then((res) => res.json())
            .then((data) => setClientData(data));
    }, []);

    return (
        <div>
            <h1>{staticContent}</h1>
            {clientData && <p>Dynamic: {clientData}</p>}
        </div>
    );
}
```

--------------------------------

### Define HTTP Request with TypeScript Response

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Defines an HTTP GET request handler using HeliumTS, demonstrating how to return a `Response` object with custom status codes and headers. This example includes user data retrieval from a database and type checking using a `User` interface. It showcases proper error handling for non-existent users.

```typescript
interface User {
    id: string;
    name: string;
    email: string;
}

export const getUser = defineHTTPRequest("GET", "/api/users/:id", async (req, ctx): Promise<Response> => {
    const userId = req.params.id;
    const user = await db.users.findById(userId);

    if (!user) {
        return new Response(JSON.stringify({ error: "User not found" }), {
            status: 404,
            headers: { "Content-Type": "application/json" },
        });
    }

    return new Response(JSON.stringify(user satisfies User), {
        status: 200,
        headers: { "Content-Type": "application/json" },
    });
});
```

--------------------------------

### Implement File Downloads with Content Disposition (TypeScript)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

This code example shows how to set up an API endpoint to serve files for download. It uses the 'Content-Disposition' header to specify the filename and 'Content-Type' as 'application/octet-stream' for binary data.

```typescript
export const downloadFile = defineHTTPRequest("GET", "/api/download/:filename", async (req, ctx) => {
    const filename = req.params.filename;
    const fileContent = await getFileContent(filename);

    return new Response(fileContent, {
        status: 200,
        headers: {
            "Content-Type": "application/octet-stream",
            "Content-Disposition": `attachment; filename="${filename}"`,
        },
    });
});
```

--------------------------------

### useFetch Hook: Advanced Options for Data Fetching

Source: https://context7.com/heliobentes/heliumts/llms.txt

Illustrates advanced configurations for the `useFetch` hook, including setting a time-to-live (ttl) for the cache, enabling automatic refetching when the window regains focus, and conditionally enabling the fetch request based on a variable.

```tsx
// src/pages/tasks.tsx (continued)
// Advanced usage with options
function TaskDetailView({ taskId }: { taskId?: number }) {
    const { data: details, isLoading, stats } = useFetch(
        getTaskDetails,
        { id: taskId! },
        {
            ttl: 30000,                    // Cache for 30 seconds
            refetchOnWindowFocus: true,     // Auto-refetch when tab regains focus
            showLoaderOnRefocus: false,     // Silent background refresh
            enabled: !!taskId               // Only fetch when taskId exists
        }
    );

    if (!taskId) return <div>Select a task to view details</div>;
    if (isLoading) return <div>Loading task details...</div>;

    return (
        <div>
            <h2>{details?.task.name}</h2>
            <p>Status: {details?.task.status}</p>
            <div>
                <h3>Comments ({details?.stats.commentCount})</h3>
                {details?.comments.map(c => (
                    <div key={c.id}>{c.text} - {c.author}</div>
                ))}
            </div>
            <div>
                <h3>Attachments ({details?.stats.attachmentCount})</h3>
                {details?.attachments.map(a => (
                    <a key={a.id} href={a.url}>{a.filename}</a>
                ))}
            </div>
            {stats && <div>Request took {stats.duration}ms</div>}
        </div>
    );
}
```

--------------------------------

### GET /api/users/:id - Get User by ID

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Retrieves a user by their unique identifier. Returns user data if found, otherwise returns a 404 error.

```APIDOC
## GET /api/users/:id

### Description
Retrieves a user by their unique identifier. Returns user data if found, otherwise returns a 404 error.

### Method
GET

### Endpoint
/api/users/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
    "id": "user-123",
    "name": "John Doe",
    "email": "john.doe@example.com"
}
```

#### Error Response (404)
- **error** (string) - Description of the error.

#### Error Response Example
```json
{
    "error": "User not found"
}
```
```

--------------------------------

### RPC (Remote Procedure Calls)

Source: https://github.com/heliobentes/heliumts/blob/main/README.md

Define server-side functions using `defineMethod` and call them from the client using `useCall` or `useFetch`. This allows for seamless communication between client and server.

```APIDOC
## RPC (Remote Procedure Calls)

Define server-side functions using `defineMethod` and call them from the client using `useCall` or `useFetch`.

### Server-Side (`defineMethod`)

**Description:**
Defines a server-side method that can be called remotely from the client.

**Example (`src/server/tasks.ts`):**
```typescript
import { defineMethod } from "heliumts/server";

export const getTasks = defineMethod(async (args: { status: string }) => {
    // Add your own database logic here
    return [{ id: 1, name: "Task 1", status: args.status }];
});

export const createTask = defineMethod(async (args: { name: string }) => {
    // Add your own create task logic
    return { id: 2, name: args.name };
});
```

### Client-Side (`useFetch`, `useCall`)

**Description:**
Hooks for fetching data and triggering mutations on the server-side methods.

**Example (`src/pages/tasks.tsx`):**
```tsx
import { useFetch, useCall } from "heliumts/client";
import { getTasks, createTask } from "heliumts/server";

export default function TasksPage() {
    const { data, isLoading } = useFetch(getTasks, { status: "open" });

    const { call: add, isCalling } = useCall(createTask, {
        invalidate: [getTasks] // Auto-refresh getTasks after success
    });

    return (
        <div>
            <button onClick={() => add({ name: "New Task" })}>
                {isCalling ? "Adding..." : "Add Task"}
            </button>
            {data?.map(task => <div key={task.id}>{task.name}</div>)}
        </div>
    );
}
```
```

--------------------------------

### Define Basic GET HTTP Endpoint in TypeScript

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Demonstrates the basic usage of defineHTTPRequest to create a simple GET endpoint that returns a JSON message. It requires importing the function from 'heliumts/server'.

```typescript
import { defineHTTPRequest } from "heliumts/server";

export const myEndpoint = defineHTTPRequest("GET", "/api/hello", async (req, ctx) => {
    return { message: "Hello World" };
});
```

--------------------------------

### JavaScript Async/Await and Arrow Function Example

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

Illustrates preferred JavaScript code style using async/await for asynchronous operations and arrow functions for callbacks. This leads to more readable and concise code compared to traditional promise chains and anonymous functions.

```javascript
// ✅ Good
const result = await fetchData();
const items = data.map((item) => item.value);

// ❌ Avoid
fetchData().then((result) => {
    const items = data.map(function (item) {
        return item.value;
    });
});
```

--------------------------------

### Cache Invalidation Example with useCall and useFetch

Source: https://github.com/heliobentes/heliumts/blob/main/docs/data-fetching.md

Demonstrates how to automatically refresh related data after a mutation by using the `invalidate` option in `useCall`. This example ensures that the `getTasks` data is refetched after adding or deleting a task.

```tsx
import { useCall, useFetch } from "heliumts/client";
import { getTasks, createTask, deleteTask } from "heliumts/server";

function TaskManager() {
    const { data: tasks } = useFetch(getTasks);

    const { call: addTask } = useCall(createTask, {
        invalidate: [getTasks], // Refetch getTasks after success
    });

    const { call: removeTask } = useCall(deleteTask, {
        invalidate: [getTasks],
    });

    return (
        <div>
            <button onClick={() => addTask({ name: "New Task" })}>Add Task</button>
            {tasks?.map((task) => (
                <div key={task.id}>
                    {task.name}
                    <button onClick={() => removeTask({ id: task.id })}>Delete</button>
                </div>
            ))}
        </div>
    );
}
```

--------------------------------

### SPA Fallback Configuration for Netlify

Source: https://github.com/heliobentes/heliumts/blob/main/docs/production-deployment.md

This configuration is used for Netlify deployments to enable Single Page Application (SPA) fallback. By defining a redirect rule in the `_redirects` file, all incoming requests are served by `index.html`, facilitating client-side routing. This is a workaround for Netlify's serverless environment, which does not support persistent WebSocket connections.

```plaintext
/*    /index.html   200
```

--------------------------------

### useRouter Hook with Catch-All Parameters in React (TSX)

Source: https://context7.com/heliobentes/heliumts/llms.txt

Illustrates how to use the 'useRouter' hook to handle dynamic routes with catch-all parameters (e.g., for documentation paths). It demonstrates accessing an array of path segments from 'router.params.slug' and constructing a full path from them. This is useful for nested routing structures.

```tsx
// Dynamic route with catch-all parameter
// src/pages/docs/[...slug].tsx
export default function DocsPage() {
    const router = useRouter();
    const slugParts = router.params.slug as string[];
    const fullPath = slugParts.join('/');

    return (
        <div>
            <h1>Documentation</h1>
            <p>Path segments: {slugParts.join(' > ')}</p>
            <p>Full path: {fullPath}</p>
        </div>
    );
}
```

--------------------------------

### HeliumTS Catch-All Routes with useRouter

Source: https://github.com/heliobentes/heliumts/blob/main/docs/routing.md

Illustrates how to implement catch-all routes in HeliumTS using the `[...param]` syntax. The `useRouter` hook provides an array of matched path segments for the catch-all parameter.

```tsx
// src/pages/docs/[...slug].tsx
import { useRouter } from "heliumts/client";

export default function DocsPage() {
    const router = useRouter();
    const slug = router.params.slug; // Array of path segments

    return <div>Docs path: {Array.isArray(slug) ? slug.join("/") : slug}</div>;
}
```

--------------------------------

### Build and Package Project

Source: https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md

These commands first compile the TypeScript source files into JavaScript in the `dist` directory, then create a compressed tarball (`.tgz`) of the project for local testing or distribution.

```bash
npm run build && npm pack
```

--------------------------------

### Layout Resolution Order Example (Helium TS)

Source: https://github.com/heliobentes/heliumts/blob/main/docs/route-groups.md

Illustrates the directory structure and the application of layout files (_layout.tsx) within different route groups and nested folders. It shows how the root layout applies universally, while group and folder layouts are scoped to their respective sections. This structure helps manage UI consistency across different parts of an application.

```tree
/pages/
  ├── _layout.tsx                    # RootLayout - applies to ALL pages
  ├── index.tsx                      # [RootLayout]
  ├── about.tsx                      # [RootLayout]
  ├── (website)/
  │   ├── _layout.tsx                # WebsiteLayout - only (website) pages
  │   ├── contact.tsx                # [RootLayout → WebsiteLayout]
  │   └── blog/
  │       ├── _layout.tsx            # BlogLayout - only blog pages
  │       └── post.tsx               # [RootLayout → WebsiteLayout → BlogLayout]
  ├── (portal)/
  │   ├── _layout.tsx                # PortalLayout - only (portal) pages
  │   ├── dashboard.tsx              # [RootLayout → PortalLayout]
  │   └── settings/
  │       ├── _layout.tsx            # SettingsLayout - only settings pages
  │       └── profile.tsx            # [RootLayout → PortalLayout → SettingsLayout]
  └── admin/
      ├── _layout.tsx                # AdminLayout - only /admin/* pages
      └── users.tsx                  # [RootLayout → AdminLayout]
```

--------------------------------

### GET /api/static-data

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

An endpoint to retrieve static data with caching enabled.

```APIDOC
## GET /api/static-data

### Description
Retrieves static data with a cache control header set for public caching for 1 hour.

### Method
GET

### Endpoint
/api/static-data

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **data** (object) - The static data.

#### Response Example
```json
{
  "key": "value"
}
```
```

--------------------------------

### Catch-All Method Endpoint

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

Demonstrates how to use the `ALL` method to match any HTTP request method for a given endpoint, useful for handling webhooks.

```APIDOC
## ALL /api/webhook

### Description
Handles any HTTP method for the `/api/webhook` endpoint, logging the request method and returning a success status.

### Method
ALL

### Endpoint
/api/webhook

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **received** (boolean) - Indicates that the request was received.

#### Response Example
```json
{
  "received": true
}
```
```

--------------------------------

### GET /api/public

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

A public endpoint configured with CORS headers for cross-origin requests.

```APIDOC
## GET /api/public

### Description
Provides public data and is configured to allow cross-origin requests from any origin with specified methods and headers.

### Method
GET

### Endpoint
/api/public

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **data** (string) - A public data message.

#### Response Example
```json
{
  "data": "public"
}
```
```

--------------------------------

### GET /api/download/:filename

Source: https://github.com/heliobentes/heliumts/blob/main/docs/http-handlers.md

An endpoint to download a file, setting the Content-Disposition header for attachment.

```APIDOC
## GET /api/download/:filename

### Description
Allows users to download a file specified by the filename in the path. The Content-Disposition header is set to prompt a file download.

### Method
GET

### Endpoint
/api/download/:filename

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to download.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- File content (binary) - The content of the requested file.

#### Response Example
(Binary file content, e.g., a PDF or image)
```json
"[Binary Data]"
```
```