Skip to content

repo-overview.md

Latest commit

 

History

History
96 lines (62 loc) · 3.94 KB

repo-overview.md

File metadata and controls

96 lines (62 loc) · 3.94 KB

Zo Space – Repo Overview

Zo Spaces is a collection of interactive web pages that a user creates with the help of Zo's AI agent.

A Zo Space derives from a base repo that includes many starter pieces. We will build on top of this template repo to help users build custom pages that fit their needs. You are allowed to install any npm dependencies if they help in serving the user's needs.

Use this document as a reference for the project structure, conventions, and common tasks.

1. Stack at a Glance

Layer Technology Purpose
Front-end Vite 7 · React 19 · TypeScript Fast dev server, modern React, type safety
UI Tailwind 4 · Radix UI primitives · shadcn/ui Rapidly build accessible, theme-able interfaces
Tooling ESLint · TypeScript strict mode · npm Code quality, dependency management

2. Directory Layout

├── src/               # React application (Vite)
│   ├── assets/        # Static images & media
│   ├── components/    # Re-usable UI blocks
│   │   └── ui/        # shadcn-generated primitive wrappers
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Client-side utilities
│   ├── pages/         # Route components – automatically discovered via convention
│   ├── App.tsx        # React root - uses import.meta.glob() for auto-routing
│   └── main.tsx       # Entry for Vite
├── public/            # Static assets copied verbatim to dist/
├── index.html         # HTML template consumed by Vite
└── *config files*     # Tailwind, Vite, eslint, tsconfig, etc.

Tip Webpack paths: the alias @ resolves to src/, so prefer to import via this path prefix, e.g. import Button from "@/components/ui/button"

3. Dependencies

• Node.js >= 18 (dependencies managed through plain npm).

4.2 Environment Variables

Create a .env file at the repo root (automatically picked up by Vite):

VITE_ZO_USER=alice # global ZO user name, provided by the system

Additional variables you add that start with VITE_ are automatically inlined into the front-end at build time.

5. Common Tasks

5.1 Add a New Page

  1. Create src/pages/<name>.tsx (convention: pages/foo/bar.tsx → route /foo/bar).
  2. Export your component as the default:
export default function MyPage() {
  return <div>Hello World</div>;
}

// Optional: mark as private (only visible in dev mode)
export const isPrivate = true;

7. Tooling Cheatsheet

Command What it does
npm run typecheck TypeScript project-wide type checking
npm run lint Run ESLint over src/

8. Conventions & Tips

• Component Library The src/components/ui/ folder contains autogenerated shadcn wrappers around Radix primitives. Generate more with npx shadcn-ui@latest add <component>. The complete registry can be looked up online.

• Theming Global CSS variables live in src/index.css. User specified themes live in src/user-theme.css. These user-themes are not to be modified directly and are autogenerated from their preferences. Prefer using shadcn color aliases like bg-primary, text-secondary, accent, muted etc. for consistency.

• Absolute Imports Use @/ instead of relative ../../ paths.

• TypeScript tsconfig.json is configured to help with catching errors at build time.