A single-page application (SPA) for molecular visualization using Molstar, built for Val Town with client-side routing.

This Val serves a React SPA with four different Molstar visualization applications:

• Home - Landing page with app navigation
• Viewer 🧬 - Standard Mol* viewer for visualizing molecular structures
• Docking Viewer 🔬 - Specialized viewer for molecular docking results
• Mesoscale Explorer 🔭 - Explore mesoscale biological structures
• MVS Stories 📖 - Interactive molecular visualization stories

Simple SPA structure with all frontend code in one place:

MolstarViewer/
├── index.html                   # HTML entry point
├── index.http.tsx               # Server: serves static files (HTTP handler)
└── frontend/                    # All client-side code

├── index.tsx               # Client entry: mounts React app
├── components/             # React components
│   ├── App.tsx            # Main app with client-side routing
│   ├── ErrorBoundary.tsx  # Error handling component
│   └── MolstarViewer.tsx  # Reusable Molstar viewer component
├── viewer/                 # Viewer-specific modules (if needed)
├── docking-viewer/         # Docking-specific modules (if needed)
├── mesoscale-explorer/     # Mesoscale-specific modules (if needed)
└── styles/                 # CSS files
    └── molstar.css         # Compiled Molstar styles

## 🛠️ Technology Stack

- **Runtime**: Val Town (Deno-based)
- **Server**: Hono v4 from JSR (static file serving only)
- **UI**: React 18.2.0 via esm.sh (client-side SPA)
- **Routing**: Custom client-side routing (History API)
- **Molstar**: JSR package `jsr:@zachcp/molstar@5.3.17`
- **Language**: TypeScript/TSX

## 🏗️ Architecture

### Server (index.http.tsx)

The server is extremely simple - it just serves static files:

```typescript
import { Hono } from "jsr:@hono/hono@4";
import { serveFile } from "https://esm.town/v/std/utils@85-main/index.ts";

const app = new Hono();

// Serve all frontend files
app.get("/frontend/*", (c) => serveFile(c.req.path, import.meta.url));

// Serve the root HTML file for all routes (SPA)
app.get("*", (c) => serveFile("/index.html", import.meta.url));

export default app.fetch;

Mounts the React app to the DOM:

import { App } from "/frontend/components/App.tsx";
import { ErrorBoundary } from "/frontend/components/ErrorBoundary.tsx";
import { createRoot } from "https://esm.sh/react-dom@18.2.0/client";
import React from "https://esm.sh/react@18.2.0";

const root = createRoot(document.getElementById("root")!);
root.render(
  <React.StrictMode>
    <ErrorBoundary>
      <App />
    </ErrorBoundary>
  </React.StrictMode>,
);

Handles client-side routing using the History API:

export function App() {
  const [currentPath, setCurrentPath] = useState(window.location.pathname);

  const navigate = (path: string) => {
    window.history.pushState({}, "", path);
    setCurrentPath(path);
  };

  // Render different views based on currentPath
  if (currentPath === "/viewer") {
    return <MolstarViewer />;
  }
  // ... etc
}

Reusable component that dynamically imports and initializes Molstar:

export function MolstarViewer({ layoutIsExpanded, layoutShowControls }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const { Viewer } = await import("jsr:@zachcp/molstar@5.3.17");
    const viewer = await Viewer.create(containerRef.current, {
      layoutIsExpanded,
      layoutShowControls,
    });
  }, []);

  return <div ref={containerRef} />;
}

import { Viewer } from "jsr:@zachcp/molstar@5.3.17";

Available exports from jsr:@zachcp/molstar:

• . (main export - includes Viewer class)
• ./plugin-ui
• ./plugin
• ./plugin-state
• ./canvas3d
• ./extensions

import { Hono } from "jsr:@hono/hono@4";

JSR (JavaScript Registry) provides native Deno/TypeScript support and works seamlessly in Val Town's runtime environment.

• ✅ HTTP entry point properly named (index.http.tsx)
• ✅ Single-page application with client-side routing
• ✅ Hono server serves static files only
• ✅ React app handles all routing client-side
• ✅ Reusable MolstarViewer component
• ✅ Dynamic import of Molstar (code splitting)
• ✅ Error boundary for error handling
• ✅ All frontend code in frontend/ folder
• ✅ Home page with navigation
• ✅ Viewer app fully functional
• ✅ Docking viewer scaffolded
• ✅ Mesoscale explorer scaffolded
• ✅ MVS Stories scaffolded

1. SPA Architecture: Server returns index.html for all routes, React handles routing
2. Client-Side Routing: Uses History API (pushState, popstate)
3. Dynamic Imports: Molstar is loaded dynamically in useEffect for code splitting
4. No Server-Side Rendering: Pure client-side React app
5. Static File Serving: Server just serves files from frontend/ directory
6. Error Handling: ErrorBoundary catches React errors, console catches runtime errors

1. Add URL parameters for loading specific structures (e.g., /viewer?pdb=1ABC)
2. Implement app-specific features:
   • Viewer: Load PDB structures by ID
   • Docking Viewer: Load and compare docking results
   • Mesoscale Explorer: Load mesoscale structures
   • MVS Stories: Story navigation and playback
3. Add loading indicators while Molstar initializes
4. Optimize bundle size with better code splitting
5. Add keyboard shortcuts and controls

• Mol* Website
• Val Town Documentation
• JSR Package Registry
• Hono Framework

• Server is a simple static file server - no server-side routes
• All routing happens client-side using History API
• Molstar is imported dynamically in the browser
• JSR imports work perfectly in client-side <script type="module"> tags
• No build step required - TypeScript runs directly in browser via esm.sh

• Single index.http.tsx at root serves as HTTP handler
• All frontend code in frontend/ directory
• Server uses serveFile utility to serve static files
• Client imports use absolute paths starting with /frontend/
• JSR imports work seamlessly in Val Town's Deno runtime

• Uses window.history.pushState() for navigation
• Listens to popstate event for back/forward buttons
• Server returns index.html for all routes (catch-all)
• React re-renders based on currentPath state

When adding new features:

1. New Routes: Add new route logic to App.tsx component
2. New Components: Create in frontend/components/
3. Shared Code: Put in frontend/ for easy importing
4. Use JSR Imports: For Molstar and other Deno-compatible packages
5. Follow Val Town Best Practices: See AGENTS.md

Example adding a new route:

// In App.tsx
if (currentPath === "/my-new-page") {
  return (
    <div>
      <h1>My New Page</h1>
      <MolstarViewer />
    </div>
  );
}

Copyright (c) 2018-2025 mol* contributors, licensed under MIT