Docs / Guides / Introduction

Getting Started with Webui

Learn how to set up, configure, and build your first application with Webui. This guide covers installation, project structure, core concepts, and best practices for production-ready development.

Installation

Webui supports multiple package managers and works seamlessly with modern JavaScript ecosystems. Run the following command to scaffold a new project:

                                Terminal
                                
                            
npm create webui@latest my-app
cd my-app
npm install
npm run dev

                                Terminal
                                
                            
yarn create webui@latest my-app
cd my-app
yarn install
yarn dev

                                Terminal
                                
                            
pnpm create webui@latest my-app
cd my-app
pnpm install
pnpm dev

ℹ️ Node.js Requirement Webui requires Node.js 18.0 or higher. We recommend using Node.js 20 LTS for the best performance and compatibility.

Project Structure

Webui follows a conventional directory structure that makes your codebase predictable and scalable:

                        File Tree
                        
                    
my-app/
├── src/
│   ├── components/     # Reusable UI components
│   ├── pages/          # Route-based page components
│   ├── layouts/        # Shared layouts & navigation
│   ├── lib/            # Utilities & configurations
│   └── app.js          # Entry point
├── public/             # Static assets
├── webui.config.js     # Project configuration
└── package.json

Core Concepts

Understanding these four pillars will help you build efficient and maintainable applications:

⚡ File-Based Routing

Routes are automatically generated from your pages/ directory structure. No manual router configuration needed.

🧩 Composable Components

Build UI with a slot-based architecture. Components are framework-agnostic and highly customizable.

🎨 Design Tokens

Centralized styling system with CSS variables, dark mode support, and theme inheritance out of the box.

🌍 Edge-Ready Deploy

Optimized builds for Vercel, Netlify, Cloudflare, and Docker. Auto-split chunks and tree-shaking included.

Quick Example

Here's how you create a responsive dashboard layout using Webui's built-in primitives:

                                Dashboard.jsx
                                
                            
import { Grid, Card, Stat, Chart } from '@webui/core';

export default function Dashboard() {
  return (
    <Grid cols={2} gap={'24px'}>
      <Stat label={"Users"} value={"12,403"} trend={+12.5} />
      <Stat label={"Revenue"} value={"$84.2k"} trend={+8.1} />
      <Chart type={"area"} data={fetchMetrics()} />
    </Grid>
  );
}

                                Dashboard.vue
                                
                            
<template>
  <Grid cols={2} gap={'24px'}>
    <Stat label={"Users"} value={"12,403"} />
    <Stat label={"Revenue"} value={"$84.2k"} />
    <Chart type={"area"} :data=metrics />
  </Grid>
</template>

<script setup>
const metrics = ref([]);
</script>

                                Dashboard.svelte
                                
                            
<script>
  import { Grid, Stat, Chart } from '@webui/core';
  let metrics = await fetchMetrics();
</script>

<Grid cols={2} gap={'24px'}>
  <Stat label={"Users"} value={"12,403"} />
  <Stat label={"Revenue"} value={"$84.2k"} />
  <Chart type={"area"} {metrics} />
</Grid>

💡 Pro Tip Use webui generate component to scaffold new UI blocks with automatic imports, type definitions, and accessibility attributes pre-configured.

Best Practices

Keep components small — Aim for single-responsibility components under 150 lines.
Lazy load routes — Use dynamic imports to reduce initial bundle size.
Leverage design tokens — Avoid hardcoded styles; use the centralized theme system.
Type your props — Webui ships with full TypeScript definitions. Enable strict: true in your config.
Test interactions — Use the built-in @webui/test utilities for snapshot and behavior testing.

⚠️ Performance Note Avoid using client-side effects on server-rendered routes. Use useTransition or Suspense boundaries to prevent hydration mismatches.

What's Next?

You're now ready to build! Explore the following guides to dive deeper into Webui's capabilities:

Routing & Nested Layouts — Master file-based routing and dynamic segments
Styling & Theming — Configure design tokens and dark mode
Deployment — Ship to Vercel, Netlify, or self-hosted Docker

← Installation Routing & Navigation →