Migration to Val Town Blog Structure

This document describes the migration from a backend/ folder structure to a top-level routes structure, following the Val Town blog pattern.

What Changed

Before (Backend Folder Pattern)

MolstarViewer/
├── index.tsx                    # Simple re-export
│   └── import app from "./backend/index.tsx"
├── backend/
│   ├── index.tsx               # Main Hono app with all routes
│   └── routes/                 # Empty directory
├── frontend/
│   └── apps/                   # App components
└── shared/

After (Val Town Blog Pattern)

MolstarViewer/
├── index.tsx                    # Main Hono app (entry point)
├── routes/                      # Individual route modules
│   ├── home.tsx
│   ├── viewer.tsx
│   ├── docking-viewer.tsx
│   ├── mesoscale-explorer.tsx
│   └── mvs-stories.tsx
├── frontend/
│   └── apps/                   # App components (unchanged)
├── shared/                      # Shared code (unchanged)
└── utils/                       # Utility functions (new)

Benefits of New Structure

Simpler Entry Point: index.tsx is now the main app, not a re-export
Modular Routes: Each route is its own Hono app in a separate file
Better Organization: Routes are at top level, making them easy to find
Follows Val Town Conventions: Matches the pattern used by Val Town's own blog
Easier to Extend: Adding new routes is as simple as creating a new file

Code Changes

Old `index.tsx`

/** @jsxImportSource https://esm.sh/react@18.2.0 */
import app from "./backend/index.tsx";

export default app;

New `index.tsx`

/** @jsxImportSource https://esm.sh/react@18.2.0 */
import { Hono } from "jsr:@hono/hono@4";
import homeRoutes from "./routes/home.tsx";
import viewerRoute from "./routes/viewer.tsx";
import dockingViewerRoute from "./routes/docking-viewer.tsx";
import mesoscaleExplorerRoute from "./routes/mesoscale-explorer.tsx";
import mvsStoriesRoute from "./routes/mvs-stories.tsx";

const app = new Hono();

app.onError((err, c) => {
  throw err;
});

app.route("/", homeRoutes);
app.route("/", viewerRoute);
app.route("/", dockingViewerRoute);
app.route("/", mesoscaleExplorerRoute);
app.route("/", mvsStoriesRoute);

export default app.fetch;

Old `backend/index.tsx` (All Routes)

const app = new Hono();

app.get("/", (c) => {
  return c.html(`<html>...</html>`);
});

app.get("/viewer", async (c) => {
  const html = renderToString(<ViewerApp />);
  return c.html(html);
});

app.get("/docking-viewer", (c) => {
  const html = renderToString(<DockingViewerApp />);
  return c.html(html);
});

// ... all routes in one file

New Route Pattern (`routes/viewer.tsx`)

/** @jsxImportSource https://esm.sh/react@18.2.0 */
import { Hono } from "jsr:@hono/hono@4";
import { renderToString } from "https://esm.sh/react-dom@18.2.0/server?deps=react@18.2.0,react-dom@18.2.0";
import { readFile } from "https://esm.town/v/std/utils@85-main/index.ts";
import ViewerApp from "../frontend/apps/viewer.tsx";

const app = new Hono();

app.get("/viewer", async (c) => {
  const molstarCss = await readFile(
    "/frontend/styles/molstar.css",
    import.meta.url,
  );
  const html = renderToString(<ViewerApp molstarCss={molstarCss} />);
  return c.html(html);
});

export default app;

Route Responsibilities

Each route file:

Creates its own Hono app instance
Defines one or more related routes
Imports necessary frontend components
Handles server-side rendering
Exports the app as default

The main index.tsx:

Creates the top-level Hono app
Imports all route modules
Mounts routes using app.route()
Sets up global error handling
Exports app.fetch for Val Town

Migration Checklist

Files That Can Be Removed

Once you're confident the migration is complete:

backend/index.tsx - Logic moved to routes
backend/routes/ - Empty directory
backend/README.md - Outdated documentation

Testing Checklist

Test home page at /
Test viewer at /viewer
Test docking-viewer at /docking-viewer
Test mesoscale-explorer at /mesoscale-explorer
Test mvs-stories at /mvs-stories
Verify Molstar initialization works
Check that CSS loads properly
Verify error handling shows full stack traces

Next Steps

Test in Val Town: Deploy and verify all routes work
Add More Features: Now easier to extend with new routes
Create Utilities: Add shared functions to utils/ as needed
Clean Up: Remove old backend/ folder once confirmed working
Document Patterns: Add examples to AGENTS.md if needed

References

Val Town Blog Structure - Inspiration
Hono Routing Documentation
Val Town Utils - readFile, serveFile, etc.

zcpbx

MolstarViewer