🚀 Getting Started with StoneJS Framework

This guide will help you get up and running with StoneJS Framework quickly. Follow these steps to install, configure, and start building your first application.

1. Prerequisites

Before you begin, make sure you have:

Node.js (version 14 or higher) - Download here
npm or yarn package manager
Basic knowledge of JavaScript and HTML
(Optional) PostgreSQL database for database features

2. Installation

Option A: Clone the Repository

# Clone the repository
git clone https://github.com/yourorg/stonejs-framework.git

# Navigate to the project
cd stonejs-framework

# Install dependencies
npm install

Option B: Install via NPM (when published)

# Create a new directory for your project
mkdir my-stonejs-app
cd my-stonejs-app

# Initialize npm
npm init -y

# Install StoneJS Framework
npm install stonejs-framework

3. Project Structure

Create the following directory structure for your application:

my-stonejs-app/
├── node_modules/
├── pages/                  # Your application pages
│   ├── index.html         # Home page
│   ├── autohandler        # (Optional) Site-wide layout
│   └── about.html         # Example page
├── .env                   # Environment variables (optional)
├── package.json
└── server.js              # Main server file

4. Create Your First Server

Create a server.js file in your project root:

const StoneJS = require('stonejs-framework');

const app = new StoneJS({
  root: './pages',
  port: 3000,
  autoReload: true  // Enable file watching in development
});

app.listen();

That's it! This simple configuration gives you:

Component-based page serving from ./pages
Template caching for better performance
Auto-reload during development
Session management
Built-in caching

5. Create Your First Page

Create pages/index.html:

<%
// Set page title in context
$context.set('title', 'Welcome');

// Get current time
const currentTime = new Date().toLocaleString();
%>

<h1>Welcome to StoneJS Framework!</h1>

<p>Current time: <%= currentTime %></p>

<p>Visit count: <%= $session.visitCount || 0 %></p>

<%
// Increment visit counter
$session.visitCount = ($session.visitCount || 0) + 1;
%>

6. Start the Server

node server.js

Open your browser and navigate to http://localhost:3000 - you should see your page!

✅ Congratulations! Your StoneJS application is now running.

7. Configuration Options

Customize your StoneJS application with these configuration options:

const app = new StoneJS({
  // Required
  root: './pages',              // Directory containing your pages
  
  // Server
  port: 3000,                   // Port to listen on
  host: '0.0.0.0',              // Host to bind to
  autoReload: true,             // Auto-reload on file changes in development
  
  // Session
  session: {
    secret: 'your-secret-key',
    resave: false,
    saveUninitialized: false,
    cookie: {
      secure: false,            // Set true for HTTPS
      httpOnly: true,
      maxAge: 86400000          // 24 hours
    }
  },
  
  // Cache
  cache: {
    store: 'memory',            // 'memory' or 'redis'
    defaultTTL: 3600            // Default cache TTL in seconds
  },
  
  // Database (optional)
  database: {
    type: 'postgresql',
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME
  },
  
  // Middleware
  middleware: [
    // Add custom Express middleware here
  ]
});

8. Environment Variables (.env)

Create a .env file for sensitive configuration:

# Server
NODE_ENV=development
PORT=3000

# Session
SESSION_SECRET=your-random-secret-key-here

# Database (optional)
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

# Redis (optional)
REDIS_HOST=localhost
REDIS_PORT=6379

Then install and use dotenv:

npm install dotenv

// In server.js (at the top)
require('dotenv').config();

9. Add a Layout with Autohandler

Create pages/autohandler to wrap all pages with a consistent layout:

<%
const pageTitle = $context.get('pageTitle') || 'My App';
%>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title><%= pageTitle %></title>
  <style>
    body { font-family: sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
    h1 { color: #667eea; }
  </style>
</head>
<body>
  <header>
    <nav>
      <a href="/">Home</a> |
      <a href="/about.html">About</a>
    </nav>
  </header>

  <main>
    <%- await next() %>
  </main>

  <footer>
    <p>© 2024 My App</p>
  </footer>
</body>
</html>

Now all pages will automatically be wrapped in this layout!

10. Next Steps

Now that you have the basics, explore these features:

Framework Features - See all available features
Autohandlers - Learn about hierarchical layouts
Dhandlers - Build REST APIs and dynamic routing
Section Tags - Organize your code with special tags
Session Management - Work with user sessions
Caching - Improve performance with caching
Database Integration - Connect to PostgreSQL
Include System - Reuse components

11. Development vs Production

Development Mode

NODE_ENV=development node server.js

# Features:
# - Auto-reload on file changes
# - Detailed error messages
# - Template cache disabled (shows changes immediately)

Production Mode

NODE_ENV=production node server.js

# Features:
# - Template caching enabled
# - Generic error messages (no stack traces)
# - Better performance

12. Common Issues

Port Already in Use

Error: EADDRINUSE: address already in use

Solution: Change the port in your configuration or kill the process using the port:

# Find process on port 3000
lsof -i :3000

# Kill it
kill -9 [PID]
  

Database Connection Failed

Error: Database connection errors

Solution:

Verify your database is running
Check .env file credentials
Ensure the database exists
Test connection with psql or database client

Template Not Found

Error: 404 Not Found

Solution:

Verify the file exists in your pages/ directory
Check file extension (.html, .ejs, etc.)
Ensure the path matches the URL

13. Getting Help

Need help?

📚 Browse the Interactive Documentation
💬 Join our community (Discord/Slack link)
🐛 Report issues on GitHub
📖 Read the Deployment Guide

Quick Reference Card

Feature	Code
Run code	`<% code %>`
Output value	`<%= value %>`
Output HTML	`<%- html %>`
Include component	`<% await include('/path') %>`
Next in chain	`<%- await next() %>`
Session data	`$session.key`
Database query	`await $db.query(sql, params)`
Cache data	`await $cache.remember(key, ttl, fn)`
Context data	`$context.set/get(key)`

You're all set! Start building your application with StoneJS Framework.

Happy coding! 🎉