panphora/hyperclay

🛠️ Developer Guide

Understanding the Code Structure

server.js
├── Configuration (lines 1-43)
│   ├── Imports (Hono, Val.town services)
│   ├── Environment variables
│   └── Storage keys
│
├── Core Services (lines 45-162)
│   ├── readBlob() - Consistent blob reading
│   └── auth object - All authentication logic
│
├── Templates & Helpers (lines 164-358)
│   ├── TEMPLATES - All HTML templates
│   ├── respond - Response helpers
│   └── handleAsync - Error handling wrapper
│
├── Middleware (lines 459-486)
│   └── requireAdmin - Protected route auth
│
└── Routes (lines 490-651)
    ├── GET / - Main app
    ├── Auth endpoints (/auth/*)
    ├── POST /save/app - Save content
    ├── GET /versions - History
    └── GET /reset-dangerous - Reset

Adding Your First Feature

Let's add a simple page counter:

1. Add Counter Display to Template

// Find DEFAULT_HTML (line ~22)
const DEFAULT_HTML = `<!DOCTYPE html>
<html>
<head>
   <script src="https://hyperclay.com/js/hyperclay-starter-kit.js"></script>
</head>
<body>
   <h1>My Notes</h1>
   <div id="counter">Views: 0</div>  <!-- Add this -->
   <textarea persist edit-mode-input></textarea>
</body>
</html>`;

2. Create Counter Logic

// Add after auth object (line ~163)
const counter = {
  async increment() {
    const key = `${APP_NAMESPACE}_counter`;
    const current = await blob.getJSON(key) || { count: 0 };
    current.count++;
    await blob.setJSON(key, current);
    return current.count;
  },
  
  async get() {
    const key = `${APP_NAMESPACE}_counter`;
    const data = await blob.getJSON(key) || { count: 0 };
    return data.count;
  }
};

3. Update Main Route

// In the GET "/" route (line ~491)
app.get("/", async (c) => {
  const html = await getCurrentHTML();
  const count = await counter.increment();  // Add this
  
  // Inject count into HTML
  const updatedHtml = html.replace(
    'Views: 0',
    `Views: ${count}`
  );
  
  // ... rest of route
  return c.html(updatedHtml);
});

Common Customizations

Change Default Template

// Line ~22 - Modify DEFAULT_HTML
const DEFAULT_HTML = `
  <!-- Your custom starting template -->
`;

Add New Route

// Add after other routes (line ~600+)
app.get("/api/stats", requireAdmin, handleAsync(async (c) => {
  const versions = await getVersionHistory();
  return c.json({
    versions: versions.length,
    lastUpdated: new Date()
  });
}));

Customize Authentication

// Modify token expiry (line ~64)
const expiry = Date.now() + (30 * 60 * 1000); // 30 mins instead of 15

Add Webhook Support

// New endpoint for external services
app.post("/webhook", handleAsync(async (c) => {
  const payload = await c.req.json();
  
  // Verify webhook secret
  const secret = c.req.header('X-Webhook-Secret');
  if (secret !== Deno.env.get('WEBHOOK_SECRET')) {
    return respond.unauthorized(c);
  }
  
  // Process webhook
  console.log('Webhook received:', payload);
  return respond.success(c, 'Webhook processed');
}));

Key Files & Functions

Component	Purpose	Line #
`STORAGE_KEYS`	All storage key patterns	37-43
`auth` object	Authentication logic	60-162
`TEMPLATES`	HTML templates	165-286
`respond`	Response helpers	289-331
`handleAsync`	Error handling	334-358
`requireAdmin`	Auth middleware	460-486
Routes	All endpoints	490-651

Environment Variables

Variable	Required	Description
`ADMIN_EMAIL`	✅ Yes	Your email for admin access
`APP_NAMESPACE`	No	Storage namespace (default: "default")
`DEBUG`	No	Enable debug logs ("true"/"false")

📚 API Reference

Public Endpoints

GET / - Main application (shows your HTML)
GET /auth/edit - Login page
POST /auth/edit - Send magic link
GET /auth/verify?token=... - Verify magic link
GET /auth/logout - Logout

Admin-Only Endpoints

POST /save/app - Save HTML (called by Hyperclay)
GET /versions - View version history
GET /reset-dangerous - Reset to default template ⚠️

🐛 Troubleshooting

Check ADMIN_EMAIL matches your email exactly
Check spam folder for magic link
Magic links expire in 15 minutes - try again

Changes Not Saving?

Make sure you're signed in (check for edit controls)
Press Ctrl+S or wait for auto-save
Check browser console for errors

Edit Mode Not Working?

Clear browser cookies and sign in again
Make sure Hyperclay script is loading (check console)
Try a different browser

Storage Limits

Free: 10MB total
Pro: 1GB total

Debug Mode

Set DEBUG=true in environment variables to see detailed logs in Val.town.

🔗 Resources

Documentation

Example Projects

Personal Site: Portfolio with editable bio and projects
Landing Page: Product page with instant updates
Documentation: Maintain docs directly in browser
Blog: Write posts without a CMS
Dashboard: Data visualization with live editing

License

Open source - use freely on Val.town.

Need more details? See valtown.md for advanced Val.town and Hono.js documentation.