🚀 ONE - Build Your AI Brand

ONE is a modern web and AI agent development toolkit that combines the blazing-fast performance of Astro with the elegant components of Shadcn/UI. This enterprise-class starter kit empowers developers to build AI-powered applications with:

⚡ High Performance: Astro’s partial hydration ensures minimal JavaScript
🎨 Beautiful UI: Pre-configured Shadcn components with full TypeScript support
🤖 AI Integration: Built-in tools for AI-powered features and automation
📱 Responsive Design: Mobile-first approach with Tailwind CSS
🔒 Type Safety: Full TypeScript support throughout the codebase
🛠️ Developer Experience: Hot reloading, intuitive project structure, and comprehensive documentation

Perfect for building modern web applications, from simple landing pages to complex AI-powered platforms.

ONE Screenshot

⚡ Quick Start

This guide will help you set up and start building AI-powered applications with ONE. ONE combines Astro, React, and modern AI capabilities to create intelligent web applications.

Prerequisites

Before you begin, ensure you have:

Node.js 18 or higher installed
pnpm package manager (npm install -g pnpm)
An OpenAI API key (for AI capabilities)
Basic knowledge of Astro and React

Quick Start

1. Get the Project 🚀

Choose your preferred way to get started with ONE:

📦 Option 1: Clone the Repository

git clone https://github.com/one-ie/one.git
cd one

💾 Option 2: Download ZIP

Download the ZIP file: Download ONE
Extract the contents
Navigate to the project directory

🔄 Option 3: Fork the Repository

Visit the Fork page
Create your fork
Clone your forked repository

☁️ Quick Start with GitHub Codespaces

Click the button above to instantly start developing in a cloud environment.

2. Install Dependencies

# Navigate to project directory
cd one

# Install dependencies
pnpm install

3. Configure Environment Variables

Make a copy .env.example file in located at the top level of your project and call it .env

Add the keys to

OPENAI_API_KEY=your_api_key_here

4. Start Development Server

pnpm dev

Visit http://localhost:4321 to see your application running.

Project Structure

one/
├── src/
│   ├── components/     # UI components
│   ├── layouts/       # Page layouts
│   ├── pages/         # Routes and pages
│   ├── content/       # Markdown content
│   └── styles/        # Global styles
└── public/           # Static assets

Adding AI Chat to a Page

Create a new page (e.g., src/pages/chat.astro):

---
import Layout from "../layouts/Layout.astro";
import { ChatConfigSchema } from '../schema/chat';

const chatConfig = ChatConfigSchema.parse({
  systemPrompt: [{
    type: "text",
    text: "You are a helpful assistant."
  }],
  welcome: {
    message: "👋 How can I help you today?",
    avatar: "/icon.svg",
    suggestions: [
      {
        label: "Get Started",
        prompt: "How do I get started with ONE?"
      }
    ]
  }
});
---

<Layout 
  title="Chat Page"
  chatConfig={chatConfig}
  rightPanelMode="quarter"
>
  <main>
    <h1>Welcome to the Chat</h1>
    <!-- Your page content here -->
  </main>
</Layout>

Customizing the Chat Interface

Chat Configuration Options

const chatConfig = {
  provider: "openai",          // AI provider
  model: "gpt-4o-mini",       // Model to use
  apiEndpoint: "https://api.openai.com/v1",
  temperature: 0.7,           // Response creativity (0-1)
  maxTokens: 2000,           // Maximum response length
  systemPrompt: "...",       // AI behavior definition
  welcome: {
    message: "...",          // Welcome message
    avatar: "/path/to/icon.svg",
    suggestions: [...]       // Quick start prompts
  }
};

Panel Modes

The chat interface can be displayed in different modes:

quarter: 25% width side panel
half: 50% width side panel
full: Full screen chat
floating: Floating chat window
icon: Minimized chat button

Adding Page-Specific Knowledge

Make your AI assistant knowledgeable about specific pages:

---
const pageContent = "Your page content here";

const chatConfig = ChatConfigSchema.parse({
  systemPrompt: [{
    type: "text",
    text: `You are an expert on ${pageContent}. Help users understand this content.`
  }],
  // ... other config options
});
---

Basic Customization

1. Styling

Customize the appearance using Tailwind CSS classes:

/* src/styles/global.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Your custom styles here */

2. Layout

Adjust the layout using the Layout component props:

<Layout
  title="Your Page"
  description="Page description"
  header={true}        // Show/hide header
  footer={true}        // Show/hide footer
  rightPanelMode="quarter"
>
  <!-- Your content -->
</Layout>

3. Chat Features

Enable or disable specific chat features:

const chatConfig = ChatConfigSchema.parse({
  // ... other options
  features: {
    textToSpeech: true,    // Enable voice synthesis
    codeHighlight: true,   // Enable code syntax highlighting
    markdown: true,        // Enable markdown rendering
    suggestions: true      // Enable quick suggestions
  }
});

🎨 Pre-installed Components

All Shadcn/UI components are pre-configured for Astro:

---
// Example usage in .astro file
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"
---

<Button>Click me!</Button>

Available Components

✅ Accordion
✅ Alert Dialog
✅ Avatar
✅ Badge
✅ Button
✅ Card
✅ Dialog
… and more!

🛠️ Project Structure

src/
├── components/                # UI Components
│   ├── ui/                   # Shadcn/UI components
│   ├── chat/                 # Chat-related components
│   └── magicui/              # Enhanced UI components
│
├── content/                  # Content Collections
│   ├── blog/                 # Blog posts
│   ├── docs/                 # Documentation
│   └── prompts/              # AI prompts
│
├── hooks/                    # React hooks
│   ├── use-mobile.tsx
│   ├── use-theme.ts
│   └── use-toast.ts
│
├── layouts/                  # Page layouts
│   ├── Blog.astro
│   ├── Docs.astro
│   ├── Layout.astro
│   └── LeftRight.astro
│
├── lib/                      # Utility functions
│   ├── utils.ts
│   └── icons.ts
│
├── pages/                    # Routes and pages
│   ├── api/                  # API endpoints
│   ├── blog/                 # Blog routes
│   ├── docs/                 # Documentation routes
│   └── index.astro          # Homepage
│
├── schema/                   # Data schemas
│   └── chat.ts              # Chat-related schemas
│
├── stores/                   # State management
│   └── layout.ts            # Layout state
│
├── styles/                   # Global styles
│   └── global.css           # Global CSS
│
└── types/                    # TypeScript types
    └── env.d.ts             # Environment types

🚀 Development Workflow

Start Development
```
npm run dev
```

Using React Components in Astro

---
// Always add client:load for interactive components
import { Dialog } from "@/components/ui/dialog"
---

<Dialog client:load>
  <!-- Dialog content -->
</Dialog>

Build for Production

npm run build
npm run preview # Test the production build

🔍 Troubleshooting

Common Issues Solved

✅ Component Hydration: All interactive components use client:load ✅ Build Warnings: Suppressed in configuration ✅ Path Aliases: Pre-configured for easy imports ✅ React Integration: Properly set up for Shadcn

💡 Pro Tips

Component Usage in Astro

---
// Always import in the frontmatter
import { Button } from "@/components/ui/button"
---

<!-- Use in template -->
<Button client:load>Click me!</Button>

Styling with Tailwind

<div class="dark:bg-slate-800">
  <Button class="m-4">Styled Button</Button>
</div>

Layout Usage

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="Home">
  <!-- Your content -->
</Layout>

📚 Quick Links

🤝 Need Help?

AI Book Generation with Pandoc

ONE includes powerful book generation capabilities that combine Astro’s content collections with Pandoc to create beautifully formatted ebooks. This system allows you to:

Manage book content through Astro’s content collections
Generate professional EPUB files with proper metadata
Maintain consistent styling across formats
Automate the book generation process

Book Content Structure

src/content/book/
├── chapters/           # Book chapters in markdown
├── assets/            # Images and resources
├── epub-style.css     # EPUB-specific styling
└── config.ts          # Book configuration

Book Schema Configuration

// src/content/config.ts
const BookSchema = z.object({
  ...CommonFields,
  author: z.string(),
  language: z.string(),
  publisher: z.string(),
  rights: z.string(),
  identifier: z.object({
    scheme: z.string(),
    text: z.string()
  }),
  creator: z.string(),
  contributor: z.string(),
  subject: z.string(),
  css: z.string().optional(),
  coverImage: z.string().optional(),
  chapter: z.number().optional(),
  order: z.number().optional(),
  status: z.enum(['draft', 'review', 'published']).default('draft')
});

EPUB Generation

Install Pandoc

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

Generate EPUB

pandoc \
  --resource-path=.:assets \
  --toc \
  --toc-depth=2 \
  --split-level=1 \
  --css=epub-style.css \
  --epub-cover-image=assets/cover.png \
  -o output.epub \
  chapters/*.md

EPUB Styling

/* src/content/book/epub-style.css */
body {
    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", sans-serif;
    line-height: 1.5;
    color: #333;
    margin: 0;
    padding: 1em;
}

h1, h2, h3, h4, h5, h6 {
    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "Helvetica Neue", sans-serif;
    color: #000;
    margin-top: 1.5em;
    margin-bottom: 0.5em;
    line-height: 1.2;
}

Features

✅ Content management through Astro collections
✅ Automatic table of contents generation
✅ Custom styling with CSS
✅ Cover image support
✅ Proper metadata handling
✅ Chapter organization
✅ Resource management
✅ Multiple output formats

Best Practices

Content Organization
- Use clear chapter naming conventions
- Maintain consistent formatting
- Keep images in the assets directory
- Use relative paths for resources
Metadata Management
- Define comprehensive book metadata
- Include all required fields
- Use proper identifiers (ISBN, etc.)
- Maintain copyright information
Styling
- Use system fonts for best compatibility
- Define consistent typography
- Ensure proper spacing
- Test on multiple devices
Build Process
- Automate EPUB generation
- Implement version control
- Add build scripts to package.json
- Include validation steps

For more details and advanced features, check out the book generation documentation.

Built with 🚀 Astro, 🎨 Shadcn/UI and Vercel AI SDK by ONE