isite documentation

What is included

Installation

Install the package from npm, then create a server using the exported factory function.

npm install isite

Minimal server

var isite = require('isite');
var site = isite({ port: 8080 });

site.loadLocalApp('client-side');
site.loadLocalApp('security');

site.run();

Startup template

git clone https://github.com/absunstar/isite-template
cd isite-template
npm i
npm start

Configuration

Pass an options object to isite(). The framework also initializes defaults for folders, cache, MongoDB, sessions, security, language, HTTPS, and local apps.

var site = require('isite')({
  port: process.env.port || 80,
  cwd: process.cwd(),
  dir: process.cwd() + '/site_files',
  upload_dir: process.cwd() + '/../uploads',
  download_dir: process.cwd() + '/../downloads',
  backup_dir: process.cwd() + '/../backup',
  apps: true,
  apps_dir: process.cwd() + '/apps',
  name: 'Your Site',
  lang: 'en',
  theme: 'default',
  mongodb: {
    enabled: true,
    host: 'localhost',
    port: '27017',
    db: 'default_db',
    collection: 'default_collection'
  },
  session: {
    timeout: 60 * 24 * 30,
    enabled: true,
    storage: 'file'
  },
  security: {
    enabled: true,
    users_collection: 'users_info',
    roles_collection: 'users_roles'
  }
});

Folder Structure

isite expects a site_files folder for public and parsed assets. Apps live in apps, while uploads, downloads, and backups can be configured.

server.js
package.json
apps/
site_files/
  css/
  js/
  html/
  fonts/
  images/
  json/
  xml/
uploads/
downloads/
backup/

Routing

Routes can return files, folders, merged files, JSON content, or callback output. Route names and request parameters are normalized to lowercase, with raw variants available when needed.

Static file routes

site.onGET({ name: ['/', '/home', '/index'], path: site.dir + '/html/index.html' });
site.onGET({ name: '/css/bootstrap.css', path: site.dir + '/css/bootstrap.min.css' });
site.onPOST({ name: '/api', path: site.dir + '/json/employees.json' });

Merge multiple files

site.onGET({
  name: '/css/style.css',
  path: [
    site.dir + '/css/bootstrap.css',
    site.dir + '/css/custom.css'
  ]
});

Callbacks, dynamic params, and wildcard routes

site.onGET('/post/:id/category/:cat_id', function (req, res) {
  res.end('Post: ' + req.params.id + ', category: ' + req.params.cat_id);
});

site.onGET('/post/*', function (req, res) {
  res.end('Any post route');
});

site.onGET('*', function (req, res) {
  res.end('Fallback route');
});

Request and Response

isite decorates request and response objects with helpers for query/body data, params, headers, rendering, JSON responses, redirects, cookies, sessions, and user features.

site.onGET('/api', function (req, res) {
  res.json({
    queryName: req.query.name,
    rawName: req.queryRaw.name,
    ip: req.ip,
    browserIsChrome: req.hasFeature('browser.chrome')
  });
});

site.onPOST('/users', function (req, res) {
  res.status(201).json({ done: true, user: req.body });
});

site.onGET('/old-url', function (req, res) {
  res.redirect('/new-url', 302);
});

Files

File helpers read from site_files by type, cache content in memory, merge files, check stats, write data, and create or remove directories.

site.html('index', function (err, content) {
  site.log(content);
});

site.readFiles([
  site.dir + '/html/head.html',
  site.dir + '/html/content.html',
  site.dir + '/html/footer.html'
], function (err, content) {
  site.log(content);
});

site.isFileExists(path, function (yes) {});
site.fileStat(path, function (err, stats) {});
site.writeFile(path, data, function (err) {});
site.removeFile(path, function (err) {});
site.createDir(path, function (err, path) {});

WebSocket

Register WebSocket endpoints with site.onWS() and connect from the browser with site.ws().

site.onWS('/chat', function (client) {
  client.onMessage = function (message) {
    if (message.type === 'connected') {
      client.send({ type: 'ready' });
    }
  };
});

<script src="/x-js/all.js"></script>
<script>
site.ws('ws://localhost/chat', function (server) {
  server.onOpen = function () {
    server.send({ type: 'accessToken', content: '##session.accessToken##' });
  };
  server.onMessage = function (msg) {
    console.log(msg);
  };
});
</script>

Cookies and Sessions

Cookies store client-side values per user. Sessions store server-side user data and are automatically associated with an access token.

site.onGET('/testSetCookie', function (req, res) {
  res.cookie('name', req.query.name);
  res.end('cookie set');
});

site.onGET('/testGetCookie', function (req, res) {
  res.end('name from cookie: ' + req.cookie('name'));
});

site.onGET('/testSetSession', function (req, res) {
  req.session.user_name = req.query.user_name;
  res.session.ip = req.ip;
  site.saveSession(res.session);
  res.end('Session set');
});

Custom Apps

Apps are modules that receive the site instance. They can register routes, words, variables, permissions, roles, and app-specific logic.

// apps/my-app/app.js
module.exports = function (site) {
  site.onGET('/my-app', function (req, res) {
    res.send('My app is loaded');
  });
};

site.importApp(FOLDER_PATH);
site.loadApp('my-app');
site.loadLocalApp('security');

Master Pages

Master pages wrap route content with shared header and footer files.

site.addMasterPage({
  name: 'main',
  header: site.dir + '/html/header.html',
  footer: site.dir + '/html/footer.html'
});

site.onGET({
  name: '/contact',
  masterPage: 'main',
  path: site.dir + '/html/contact.html',
  parser: 'html'
});

HTML Server Tags and Attributes

Enable parser: 'html' to import site files, inject variables, use words, and show content conditionally by language, permission, login state, browser, operating system, or IP.

site.var('siteName', 'First Site With isite');
site.onGET({ name: '/', path: site.dir + '/html/index.html', parser: 'html' });

<style x-import="page.css"></style>
<div x-import="navbar.html"></div>
<title>##var.siteName##</title>
<h2>##word.user_name##</h2>

<div x-lang="Ar">Arabic content</div>
<div x-permission="admin">Admins only</div>
<div x-feature="login">Logged-in users</div>
<div x-feature="browser.chrome">Chrome users</div>

MongoDB

Use site.connectCollection() for high-level collection access, or site.mongodb for lower-level database operations.

var employees = site.connectCollection('employees', 'company');

employees.insertOne({ name: 'amr', salary: 50000 }, function (err, doc) {});

employees.findMany({
  where: { name: /a/i },
  select: { name: 1, salary: 1 },
  limit: 50,
  skip: 10,
  sort: { salary: -1 }
}, function (err, docs, count) {});

employees.updateOne({
  where: { id: 5 },
  set: { salary: 30000 }
}, function (err, result) {});

employees.deleteOne({ where: { id: 5 } }, function (err, result) {});

site.backupDB();
site.restoreDB();
employees.createIndex({ name: 1 }, {}, function (err, result) {});
employees.createUnique({ email: 1 }, function (err, result) {});

Upload and Download

isite parses uploaded files and provides response helpers for forced downloads.

<form action="uploadFile" method="post" enctype="multipart/form-data">
  <input type="file" name="fileToUpload" />
  <input type="submit" />
</form>

site.onPOST('uploadFile', function (req, res) {
  var response = { done: true };
  var file = req.files.fileToUpload;
  var newpath = site.options.upload_dir + '/' + file.originalFilename;

  site.mv(file.filepath, newpath, function (err) {
    if (err) {
      response.done = false;
      response.error = err;
    }
    res.json(response);
  });
});

site.onGET('/files/file1.zip', function (req, res) {
  res.download(site.options.download_dir + '/file1.zip', 'info.zip');
});

Multi Language

Store translated words in site_files/json/words.json, use ##word.name## in HTML, and switch language with /x-language/change.

[
  { "name": "user_name", "En": "User Name", "Ar": "اسم المستخدم" },
  { "name": "user_email", "En": "Email", "Ar": "البريد الالكترونى" }
]

<label>##word.user_name##</label>
<div x-lang="Ar">Arabic content</div>
<div x-lang="En">English content</div>

Client Libraries and Charts

The client-side app exposes common browser libraries through fixed routes. The charts app adds local chart creation helpers.

site.loadLocalApp('client-side');
site.loadLocalApp('charts');

<link rel="stylesheet" href="/x-css/bootstrap3.css" />
<link rel="stylesheet" href="/x-css/font-awesome.css" />
<script src="/x-js/jquery.js"></script>
<script src="/x-js/bootstrap3.js"></script>
<script src="/x-js/angular.js"></script>

Helpers

isite includes helpers for rendering, hashing, encoding, JSON conversion, object copying, and feature checks.

res.render('index.html', { name: 'amr' }, {
  compress: true,
  cache: false,
  parser: 'html css js'
});

var copy = site.copy({ name: 'amr' });
var hash = site.md5('content');
var base64 = site.toBase64('content');
var normal = site.fromBase64(base64);
var jsonString = site.toJson(copy);
var jsonObj = site.fromJson(jsonString);

Events

Global events let apps and routes communicate across the site lifecycle.

site.on('event name', function (obj) {
  site.log('name: ' + obj.name);
});

site.call('event name', { name: 'x1' });

site.on('sync event name', function (obj, callback, next) {
  site.log(obj.name);
  next();
});

site.quee('sync event name', { name: 'x2' });

API Reference

Complete Function Index

This index lists the public and commonly consumed functions found in the isite source. Some aliases call the same implementation, so they are grouped together.

AI Agent Files

These files are included to help AI coding agents understand the library quickly and make safer changes in this repository.