NS HELIX React Boilerplate

A modern template for developing HELIX WebUI interfaces using React, TypeScript, Vite, and TailwindCSS.

✨ Features

• React 19 with TypeScript
• Vite for fast builds and hot reload
• TailwindCSS 4.0 for styling
• Custom hooks for HELIX WebUI integration
• ESLint configured for React
• Project structure optimized for HELIX
• Visibility provider for interface management

🚀 Quick Start

You can create a new project using this template in two ways:

Method 1: Using npx (recommended)

npx ns-htemplate my-helix-project

Method 2: Manual clone

git clone https://github.com/Simomagy/ns-htemplate.git my-helix-project
cd my-helix-project
rm -rf .git bin/ .npmignore
npm install

📋 Project Structure

my-helix-resource/
├── src/
│   ├── components/         # React components
│   │   ├── App.tsx
│   │   └── Background.tsx  # Background layer
│   ├── hooks/             # Custom hooks
│   │   └── onClientEvent.ts
│   ├── providers/         # Context providers
│   │   └── VisibilityProvider.tsx
│   ├── utils/             # Utilities
│   │   ├── debugData.ts
│   │   ├── sendToClient.ts    # Wraps hEvent
│   │   ├── luaLog.ts          # Console logging
│   │   └── misc.ts
│   ├── index.css          # Global styles
│   ├── main.tsx           # Entry point
│   └── vite-env.d.ts      # TypeScript definitions
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── postcss.config.mjs

🛠️ Available Scripts

# Start development server
npm run dev

# Build for development with watch mode (for HELIX)
npm run build:watch

# Production build
npm run build

🎯 HELIX Usage

1. Development

During development, use:

npm run build:watch

This command will build the project in watch mode, automatically updating files when you make changes.

2. WebUI Communication

The template includes hooks and utilities for communicating with the HELIX client:

onClientEvent Hook

Listen for events sent from Lua to JavaScript.

Lua:

ui:SendEvent("showNotification", { message = "Hello from Lua" })

JavaScript:

import { onClientEvent } from "./hooks/onClientEvent";

function MyComponent() {
  onClientEvent<{ message: string }>("showNotification", (data) => {
    console.log(data.message);
  });

  return <div>My Component</div>;
}

sendToClient Utility (hEvent wrapper)

Send data from JavaScript to Lua, optionally with a callback.

JavaScript:

import { sendToClient } from "./utils/sendToClient";

const handleClick = async () => {
  try {
    const response = await sendToClient<{ success: boolean }>("myCallback", {
      data: "some data",
    });
    console.log(response.success);
  } catch (error) {
    console.error("Error:", error);
  }
};

Lua:

ui:RegisterEventHandler("myCallback", function(eventData, callback)
    print(eventData.data)
    callback({ success = true })
end)

3. Logging to Lua Console

Send formatted logs from React to the HELIX Lua console:

JavaScript:

import { log } from "./utils/luaLog";

// Quick logging helpers
log.info("User logged in", { userId: 123 });
log.error("API call failed", { status: 404 });
log.debug("Current state", { visible: true });

Logs are color-coded and formatted automatically in the Lua console.

4. Visibility Management

The VisibilityProvider automatically manages interface visibility:

// The interface will automatically hide when ESC is pressed
// or when it receives the 'setVisible' event with false

🎨 Customization

Background Component

Customize your UI background easily:

import { Background } from "./components/Background";

<Background
  imageUrl="/assets/background.jpg"
  opacity={0.6}
  blur={4}
  overlay="rgba(0, 0, 0, 0.5)"
/>

TailwindCSS

The project uses TailwindCSS 4.0. You can customize colors and themes by modifying the CSS configuration file in src/index.css.

TypeScript

TypeScript configurations are optimized for React and Vite. You can modify tsconfig.json for your specific needs.

📦 Build and Deployment

1. For HELIX development:

   npm run build:watch

2. For production:

   npm run build

Built files will be in the build/ folder and can be copied to your HELIX resource.

🤝 Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is released under the MIT License. See the LICENSE file for more details.

🙏 Acknowledgments

• React
• Vite
• TailwindCSS
• HELIX

Made with ❤️ for the HELIX community