This guide will help you set up and start building AI-powered applications using the ONE framework. ONE combines Astro, React, and
Quick Start
1. Get the Project
You have three options to get started with ONE:
# Option 1: Clone the repository
git clone https://github.com/one-ie/one.git
# Option 2: Download the ZIP file
# Visit: https://github.com/one-ie/one/archive/refs/heads/main.zip
# Option 3: Fork the repository
# Visit: https://github.com/one-ie/one/fork
You can also create a new project directly in GitHub Codespaces: Open in Codespaces
2. Install Dependencies
# Navigate to project directory
cd one
# Install dependencies
pnpm install
3. Configure Environment Variables
Create a .env
file in your project root:
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 panelhalf
: 50% width side panelfull
: Full screen chatfloating
: Floating chat windowicon
: 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
}
});
Common Issues
Troubleshooting
-
API Key Issues
- Ensure your OpenAI API key is properly set in
.env
- Check API key permissions and quotas
- Ensure your OpenAI API key is properly set in
-
Build Errors
- Run
pnpm clean
to clear cache - Ensure all dependencies are installed
- Check for Node.js version compatibility
- Run
-
Chat Not Working
- Verify API endpoint configuration
- Check browser console for errors
- Ensure proper network connectivity
Support
Need help? Try these resources:
Remember to check the Frequently Asked Questions for common queries and solutions.