Hugging Face's logo

Spaces:
STEFTM
/
osw-studio
Sleeping

App Files Community
osw-studio / docs /PROJECTS.md
otst's picture
otst
es module support, theming, compaction and stability improvements
716b726
preview code
|
raw
history blame contribute delete
8.62 kB

Managing Projects

Everything you need to know about creating, organizing, and exporting projects.

Creating Projects

  1. Click Projects in the sidebar
  2. Click + New Project
  3. Enter a project name
  4. Choose a template:
    • Website Starter - Minimal starting point with basic HTML/CSS/JS structure
    • Starter (Handlebars) - Handlebars starter with templating
    • Example Studios - Pre-built multi-page portfolio example
    • Starter (React + TypeScript) - Minimal React app with auto-bundling
    • React Demo: Task Tracker - Interactive task tracker showcasing React components and state
    • Starter (Preact + TypeScript) - Lightweight React alternative with signals
    • Starter (Svelte) - Svelte 5 app with compile-time reactivity
    • Starter (Vue) - Vue 3 app with Composition API
    • Starter (Python) - Python script with Pyodide WASM runtime
    • Starter (Lua) - Lua script with wasmoon WASM runtime
    • Landing Page with Contact Form - Contact form with Resend email (Backend)
    • Blog with Comments - Blog with auth and moderated comments (Backend)
    • Or select any custom template you've created
  5. Optionally add a description
  6. Click Create Project

All projects start from a template. The built-in templates provide a foundation to build upon.

Learn more about templates →

Opening Projects

From Projects View

  1. Click Projects in the sidebar
  2. Find your project in the grid
  3. Click on the project card

Recent Projects

Your 3 most recent projects appear in the sidebar for quick access.

Project Workspace

The workspace displays up to 3 panels side-by-side. Open, close, and reorder panels from the sidebar or panel headers — drag the grip handle in a panel header to rearrange. Panel widths, order, and visibility persist between sessions.

Available panels: Chat, File Explorer, Code Editor, Preview, Console (Python/Lua), Skills, Checkpoints, Debug, Settings. When you open a 4th panel, the rightmost panel is replaced.

Workspace Header

The header contains key controls:

  • Project name - Displayed in the header
  • Mode toggle - Switch between Chat (read-only) and Code (full access) modes
  • Deployment selector (Server Mode only) - Choose which published deployment's backend context to load

Deployment Selector (Server Mode)

In Server Mode, a dropdown appears in the workspace header that lets you select a deployment. When selected:

  • The AI gains awareness of that deployment's backend features
  • A /.server/ hidden folder appears with server context files
  • You can ask the AI about edge functions, database schema, etc.

See Server Mode → Server Context Integration for details.

Chat

Talk to AI to build and modify your project. The chat panel has two modes:

Chat Mode (read-only):

  • AI uses read-only shell commands
  • Explore and discuss without making changes
  • See how the AI understands your project
  • Perfect for planning before building

Code Mode (full access):

  • AI can create, edit, and delete files
  • Make actual changes to your project
  • Build features and fix bugs

Pro tip: If unsure, start with Chat mode to see how the AI views your project. You can also one-shot prompt full multi-page websites, though smaller, focused tasks are generally more consistent.

File Explorer

Browse your project structure:

  • Click folders to expand/collapse
  • Click files to open in editor
  • Right-click for options (rename, delete, etc.)
  • Right-click and select Show Hidden Files to view hidden folders

Hidden Folders

OSW Studio uses hidden folders (starting with .) to provide AI context:

Folder Icon Purpose
/.skills/ Purple book Skill documents that teach the AI your preferences
/.server/ Orange server Server context (Server Mode only) - database schema, edge functions, etc.

These folders are read-only and transient - their contents are generated dynamically to provide context to the AI and are not saved with your project

Code Editor

View and edit code:

  • Multiple tabs for different files
  • Syntax highlighting
  • Save with Cmd/Ctrl+S
  • Supports HTML, CSS, JavaScript, TypeScript, TSX, JSON, Markdown, XML, SVG, Python, Lua, Svelte, Vue SFCs

Live Preview

See your website in real-time:

  • Updates automatically when files change
  • Click links to navigate
  • Test responsive design with mobile/tablet/desktop size presets
  • Click Maximize to fill the whole screen with the preview (hides all other panels)
  • Open in new tab for full testing
  • Use the focus tool to select specific elements and add them to message context for targeted AI edits
  • Drag semantic blocks from the Blocks palette onto the preview — the AI writes code that fits your project

Console (Python/Lua)

For terminal runtimes (Python, Lua), the Console panel shows script output and lets you see errors from script execution. Opens automatically for terminal runtimes.

Saving Your Work

Manual Save

Press Ctrl+S (Windows/Linux) or Cmd+S (Mac) to save your project.

Important: Projects require manual save to persist. While checkpoints are created automatically during AI operations, you must manually save to create a permanent restore point.

Checkpoints

OSW Studio creates checkpoints automatically after AI makes changes:

  • Starting point is created when you open a project (if no prior save exists)
  • Auto-checkpoints are created during AI operations (last 10 kept per project)
  • Manual saves (Cmd/Ctrl+S) persist across refreshes and are never evicted
  • "Discard Changes" reverts to the state when you opened the project — your last manual save if one exists, or the Starting Point otherwise

How to restore:

  1. Open the Checkpoints Panel in the workspace
  2. Browse starting point, auto-checkpoints, and manual saves
  3. Click any checkpoint to restore your project to that state

Exporting Projects

Export as ZIP

Download your complete website ready to deploy:

  1. Click the Menu icon (⋮) in the top right
  2. Select Export
  3. Choose ZIP (suitable for hosting)
  4. Save the ZIP file

The ZIP contains:

  • All HTML, CSS, JavaScript files
  • Images and assets
  • Clean structure ready for hosting

Deploy it to:

  • Vercel, Netlify, GitHub Pages
  • Any static file host
  • Your own server

Deployment guide →

Export as JSON (Backup)

Save your entire project including chat history and checkpoints:

  1. Click the Menu icon (⋮)
  2. Select Export
  3. Choose JSON (backup format)
  4. Save the file

Use this to:

  • Back up your work
  • Transfer projects between computers
  • Share projects with others
  • Keep complete history

Import JSON Files

Restore a backed-up project:

  1. Click Projects in sidebar
  2. Click Import Project
  3. Select your .json backup file
  4. Project loads with full history

Organizing Projects

Naming

Give projects clear names:

  • ✅ "Portfolio Website"
  • ✅ "Client Landing Page - Acme Corp"
  • ✅ "Blog v2"
  • ❌ "Untitled 1"
  • ❌ "New Project"

Deleting Projects

  1. Go to Projects view
  2. Find the project
  3. Click the Delete button (trash icon)
  4. Confirm deletion

⚠️ Warning: Deletion is permanent. Export a backup first if you might need it later.

Tips for Project Management

💡 Name Projects Clearly You'll thank yourself later when you have many projects

💡 Export Backups Regularly Especially before major changes or experiments

💡 Use Templates Don't rebuild the same structure every time

💡 One Feature at a Time Make changes incrementally and test as you go

💡 Test in Preview Always check the live preview before exporting

💡 Keep Chat History Clean Start new conversations when switching to different features

Common Tasks

Duplicate a Project

  1. Export project as JSON
  2. Import it back with a new name
  3. Continue working on the copy

Start Over

  1. Delete old project
  2. Create new project with same name
  3. Or keep old as reference and create new

Share a Project

  1. Export as JSON
  2. Share file with others
  3. They import it in their OSW Studio

Next Steps: