Skip to content

Commit 9194a0c

Browse files
lambdalisuelambdalisue
committed
refactor!: migrate from Deno to Node.js + HonoX + Vite SSG
Replace custom Deno-based SSG with standard Node.js tooling to improve maintainability and align with broader ecosystem. The migration enables faster build times, better IDE support, and easier contributor onboarding. BREAKING CHANGE: Build system changed from Deno to Node.js - Runtime: Deno → Node.js v22+ - Framework: Custom SSG → HonoX + Vite SSG - Commands: `deno task` → `npm run` - Entry: main.ts → app/server.ts Key changes: - Adopt HonoX file-based routing with dynamic routes ([slug].tsx, [package].tsx) - Split components into app/components/ for reusability - Consolidate duplicate code (SearchModal, ScrollToTop, Header) - Support both /docs.md and /docs/index.md URL styles for markdown endpoints - Use Hono app composition to prioritize explicit routes over dynamic routes - Add basePath() helper for GitHub Pages deployment - Replace inline scripts with bundled client.ts via Vite - Update documentation to reflect new architecture Migration preserves all functionality: - ✅ Static site generation with SSG - ✅ Markdown documentation with /path/index.md endpoints - ✅ API reference JSON/Markdown endpoints - ✅ llms.txt generation - ✅ Pagefind search integration - ✅ Dark mode, code highlighting, copy buttons
1 parent cb1ccd4 commit 9194a0c

55 files changed

Lines changed: 1630 additions & 5356 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,27 @@ Documentation for Probitas - a scenario-based testing framework for Deno.
44

55
## Quick Reference
66

7-
- **Runtime**: Deno 2.x
8-
- **Framework**: Hono
7+
- **Runtime**: Node.js + HonoX + Vite SSG
8+
- **API Generation**: Deno (for generate-api-docs.ts)
99
- **Deploy**: GitHub Pages
1010

1111
## Commands
1212

1313
```bash
14-
deno task dev # Dev server with watch
15-
deno task verify # Run fmt, lint, check, test
16-
deno task build # Build static site
14+
npm run dev # Dev server with HMR
15+
npm run build # Build static site (client + SSG + Pagefind)
16+
npm run preview # Preview production build
17+
18+
# API docs generation (requires Deno)
19+
deno run -A scripts/generate-api-docs.ts
1720
```
1821

1922
## Pre-Completion Verification
2023

2124
BEFORE reporting task completion, run and ensure zero errors:
2225

2326
```bash
24-
deno task verify
27+
npm run build
2528
```
2629

2730
## Reference Probitas Packages

‎.claude/rules/architecture.md‎

Lines changed: 53 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
paths: "main.ts, lib/**/*.ts, templates/**/*.tsx, scripts/**/*.ts"
2+
paths: "app/**/*.{ts,tsx}, scripts/**/*.ts, vite.config.ts"
33
---
44

55
# Site Architecture
@@ -8,34 +8,53 @@ paths: "main.ts, lib/**/*.ts, templates/**/*.tsx, scripts/**/*.ts"
88

99
```
1010
documents/
11-
├── main.ts # Entry point (Deno.serve)
12-
├── deno.json # Project configuration
13-
├── docs/ # Markdown documentation source
14-
├── data/
11+
├── app/ # Application source
12+
│ ├── server.ts # HonoX entry point
13+
│ ├── client.ts # Client-side JavaScript (bundled by Vite)
14+
│ ├── routes/ # HonoX file-based routes
15+
│ │ ├── _renderer.tsx # Global layout renderer (jsxRenderer)
16+
│ │ ├── index.tsx # Home page route
17+
│ │ ├── AI.tsx # AI documentation route
18+
│ │ ├── api/
19+
│ │ │ ├── index.tsx # API index route
20+
│ │ │ └── [package].tsx # Dynamic API package route
21+
│ │ └── docs/
22+
│ │ ├── index.tsx # Docs index route
23+
│ │ └── [slug].tsx # Dynamic docs route
24+
│ ├── templates/ # Page-level JSX components
25+
│ │ ├── Layout.tsx # Main layout component
26+
│ │ ├── HomeLayout.tsx # Home page layout
27+
│ │ ├── components.tsx # Shared UI components
28+
│ │ ├── home.tsx # Home page template
29+
│ │ ├── scripts.ts # Inline scripts for SSG
30+
│ │ ├── api/ # API page templates
31+
│ │ └── docs/ # Documentation page templates
32+
│ ├── components/ # Reusable UI components
33+
│ │ ├── Header.tsx # Global header navigation
34+
│ │ ├── SearchModal.tsx # Search modal component
35+
│ │ ├── ScrollToTop.tsx # Scroll-to-top button
36+
│ │ ├── TableOfContents.tsx # Table of contents sidebar
37+
│ │ └── DocLayout.tsx # Documentation page layout
38+
│ └── lib/ # Core modules
39+
│ ├── api-docs.ts # API documentation types & utilities
40+
│ ├── api-markdown.ts # API markdown generation
41+
│ ├── markdown.ts # Markdown processing & link rewriting
42+
│ ├── llms.ts # LLM-friendly endpoints generation
43+
│ ├── path.ts # basePath() helper for GitHub Pages
44+
│ ├── signature-formatters.ts # Type signature formatting
45+
│ └── type-references.ts # Type reference resolution
46+
├── data/ # Data modules
1547
│ ├── api/ # Generated API JSON (deno doc --json)
16-
│ ├── index/ # Example scenario index files
17-
│ └── docs.ts # Documentation pages configuration
18-
├── templates/ # Hono JSX components
19-
│ ├── api/ # API reference page templates
20-
│ ├── docs/ # Documentation page templates
21-
│ ├── Layout.tsx # Main layout component
22-
│ ├── HomeLayout.tsx # Home page layout
23-
│ ├── components.tsx # Shared UI components
24-
│ ├── home.tsx # Home page template
25-
│ └── scripts.ts # Client-side JavaScript (theme, carousel, etc.)
26-
├── lib/ # Core modules
27-
│ ├── api-docs.ts # API documentation types & utilities
28-
│ ├── api-markdown.ts # API markdown generation
29-
│ ├── markdown.ts # Markdown processing & link rewriting
30-
│ ├── llms.ts # LLM-friendly endpoints generation
31-
│ ├── signature-formatters.ts # Type signature formatting
32-
│ └── type-references.ts # Type reference resolution
33-
├── static/ # Static assets (CSS, images, favicon)
48+
│ ├── docs.ts # Documentation pages configuration
49+
│ └── api-pages.ts # API documentation loader
50+
├── docs/ # Markdown documentation source
51+
├── public/ # Static assets (CSS, images, favicon)
3452
├── scripts/ # Build and generation scripts
35-
│ ├── build.ts # SSG build + Pagefind indexing
53+
│ ├── post-build.js # Pagefind indexing & llms.txt.html→llms.txt rename
3654
│ └── generate-api-docs.ts # Fetch & process API docs from JSR
37-
├── tests/ # Integration tests
38-
└── probitas/ # Example Probitas scenarios
55+
├── package.json # npm dependencies
56+
├── vite.config.ts # Vite + HonoX SSG configuration
57+
└── tsconfig.json # TypeScript configuration
3958
```
4059

4160
## Routes
@@ -57,11 +76,9 @@ documents/
5776
### 1. API Documentation Generation
5877

5978
```bash
60-
deno task generate-api
79+
deno run -A scripts/generate-api-docs.ts
6180
```
6281

63-
Runs `scripts/generate-api-docs.ts`:
64-
6582
1. Fetches all `@probitas/*` packages from JSR API
6683
2. Runs `deno doc --json` for each package
6784
3. Processes and filters exports (removes private items, imports, etc.)
@@ -71,21 +88,20 @@ Runs `scripts/generate-api-docs.ts`:
7188
### 2. Static Site Generation
7289

7390
```bash
74-
deno task build
91+
npm run build
7592
```
7693

77-
Runs `scripts/build.ts`:
78-
79-
1. **SSG**: Uses Hono's `toSSG()` to generate HTML/JSON/Markdown files
80-
2. **Asset Copy**: Copies `static/` contents to `dist/static/`
81-
3. **Search Index**: Runs Pagefind to generate searchable index
94+
1. **Client Build**: Builds client.ts → dist/static/client.js
95+
2. **SSG Build**: HonoX + Vite SSG generates HTML/JSON/Markdown files (Vite automatically copies public/ to dist/)
96+
3. **Post-Build**: Renames llms.txt.html → llms.txt, runs Pagefind
8297

8398
## Client-Side Features
8499

85-
The site includes JavaScript functionality (see `templates/scripts.ts`):
100+
The site includes JavaScript functionality (see `app/client.ts` and `app/templates/scripts.ts`):
86101

87102
- **Theme switching**: Light/dark mode with localStorage persistence
88103
- **Code highlighting**: Dynamic highlight.js loading with theme sync
89104
- **Code copy buttons**: Copy-to-clipboard for code blocks
90105
- **Carousel**: Interactive example carousel on home page
91-
- **Scroll indicators**: Fade effects for scrollable navigation
106+
- **Search modal**: Pagefind-powered search (Cmd/Ctrl+K)
107+
- **Scroll-to-top**: Floating button for long pages

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@
33
.worktrees
44
.playwright-mcp
55
dist/
6+
node_modules/
7+
package-lock.json

0 commit comments

Comments
 (0)