📚 StoneJS Developer Guide
Complete reference for building modern web applications with the StoneJS Framework
🏗️ Architecture
Request Flow
How a request flows through StoneJS:
- Request arrives at Express server
- Middleware runs (session, database, cache)
- Route resolution matches URL to file/dhandler
- Autohandler chain executes from root to current directory
- Page/Component renders with EJS templating
- Autohandler wrapping applies layouts in reverse order
- Response sent to client
Directory Structure
stonejs-framework/
├── pages/ # Your application pages
│ ├── index.html # Root page (/)
│ ├── autohandler # Root layout (wraps all pages)
│ ├── about.html # /about.html
│ ├── components/ # Reusable components
│ │ ├── header.html
│ │ └── footer.html
│ ├── admin/ # Admin section
│ │ ├── autohandler # Admin layout
│ │ ├── index.html # /admin/
│ │ └── users.html # /admin/users.html
│ └── api/ # API routes
│ └── dhandler # Handles /api/*
├── lib/ # Framework core
│ ├── middleware/ # Middleware modules
│ └── utils/ # Utility functions
├── stonejs-app.js # Application entry point
├── index.js # Framework core
├── package.json
└── .env # Configuration
File Types
| File Type | Purpose | Example |
|---|---|---|
*.html |
Regular pages and components | pages/about.html |
autohandler |
Layout wrapper for pages in directory | pages/autohandler |
dhandler |
Dynamic route handler (API/custom routing) | pages/api/dhandler |
index.html |
Default page for directory | pages/admin/index.html |
Component Lifecycle
<%%doc>
Documentation block - removed at runtime
Use for developer notes and comments
<%%once>
// Runs ONCE per server startup
// Perfect for expensive initialization
const config = loadConfiguration();
<%%init>
// Runs at REQUEST START
// Before page rendering begins
initializeRequestContext();
<%%js>
// Inline JavaScript block
// Runs during template rendering
const data = await fetchData();
<!-- Your HTML with EJS tags -->
<h1><%= data.title %></h1>
<%%cleanup>
// Runs at REQUEST END
// After response is sent
logRequestMetrics();
Middleware Stack
StoneJS uses Express middleware in this order:
- Body Parser - Parses JSON and URL-encoded request bodies
- Session Middleware - Manages user sessions
- Database Middleware - Attaches database connection pool
- Cache Middleware - Attaches caching manager
- Static Files - Serves static assets from
pages/ - Component Renderer - Processes .html files and dhandlers
Need more help?