3.9 KiB
Project
Environment
You are working inside a VCH cloud development environment.
- OS: Debian-based LXC container
- Editor: code-server (VS Code in browser) on port 8080
- CLI: Claude Code is available as
claudein terminal - Git: Pre-configured. Gitea integration available through VCH.
- Preview: Start a dev server on any port — VCH detects listening ports automatically and provides preview URLs with SSL.
- Publishing: Assign a public subdomain to any port via the VCH Publish page (automatic SSL).
- User:
vchuserwith home at/home/vchuser
Preview Access (IMPORTANT)
Apps are accessed through a reverse proxy, not directly. There are two modes:
- Subdomain proxy (preferred):
https://lxc{VMID}-{PORT}.dev.example.com/— your app is at the domain root, everything works normally. - Path-based proxy (fallback):
https://host/proxy/{INSTANCE}/p/{PORT}/— your app is behind a path prefix.
Rules for portable apps that work in both modes:
- ALWAYS use relative paths for assets, API calls, and links:
css/style.css✅ — NOT/css/style.css❌api/users✅ — NOT/api/users❌fetch('api/data')✅ — NOTfetch('/api/data')❌
- Static file serving: Configure your server to serve from the request path, not the filesystem root.
<base>tag: If you must use absolute paths, add<base href="./">in<head>.
Framework-specific configuration:
- Express:
app.use(express.static('public'))works — just ensure HTML references are relative. - Vite: Set
base: './'invite.config.ts. - Next.js: Set
basePathinnext.config.jsif using path-based proxy, or leave default for subdomain proxy. - Create React App: Set
"homepage": "."inpackage.json.
Development Conventions
- Write clear, descriptive commit messages (imperative mood: "Add feature", not "Added feature")
- Prefer small, focused commits over large ones
- Run linters and formatters before committing
- Write tests for critical business logic
- Keep dependencies minimal — use native browser/Node APIs where possible
README Requirement (MANDATORY)
Every project MUST have a meaningful README.md in the project root. This is enforced by the VCH audit system — projects without a proper README cannot be published.
Your README must include at minimum:
- Project description — what the project does (not just the template placeholder)
- Installation instructions — how to install dependencies
- Development instructions — how to start the dev server
- Tech stack — what technologies are used
Update the README whenever you add features, change setup steps, or modify the tech stack. The audit will reject READMEs that are still just the default template.
Project Description (MANDATORY)
Every project has a .vch-description file in the project root. Keep this file up to date with a clear, non-technical description of your project:
- What the project does
- What problem it solves or what it's used for
- Who it's for
Do NOT include technical details (tech stack, dependencies, setup instructions) — those belong in the README. The .vch-description content is shown in the VCH Showcase and is synced automatically when an audit runs.
Update .vch-description whenever the project's purpose or scope changes significantly.
Web Best Practices
- Use semantic HTML elements (
nav,main,article,section, etc.) - Mobile-first responsive design
- Follow accessibility guidelines (ARIA labels, keyboard navigation, color contrast)
- Optimize images and assets for performance
- Use environment variables for configuration — never hardcode secrets
Commands
Fill in project-specific commands below:
- Install dependencies:
npm install - Start dev server:
npm run dev - Run tests:
npm test - Build for production:
npm run build - Lint:
npm run lint