Extensions

js-cgi uses shared library extensions (.so) to add functionality. Extensions are loaded via the INI file and register new global objects and functions into every script.

Built-in Extensions

ExtensionGlobalDescription
sqlite.sosqliteSQLite database with parameterised queries and transactions
session.sosessionCookie-based sessions with file storage
file.sofileFilesystem read, write, append, delete, list
crypto.socryptoHashing (MD5, SHA), HMAC, random bytes, UUID
http.sohttpOutbound HTTP client (GET, POST, PUT, DELETE)
mysql.somysqlMySQL/MariaDB with parameterised queries and transactions
smtp.sosmtpSend emails via SMTP with TLS support

Enabling Extensions

Extensions are enabled in /etc/js-cgi/js-cgi.ini:

extension_dir = /usr/lib/js-cgi/modules
extension = sqlite.so
extension = session.so
extension = file.so
extension = crypto.so
extension = http.so
extension = mysql.so
extension = smtp.so

How Extensions Work

When js-cgi starts, it:

  1. Reads the INI file for extension directives
  2. Loads each .so file from the extension_dir
  3. Calls the extension's init function, which registers globals
  4. Executes your script with those globals available
  5. Calls the extension's shutdown function after the script completes

Only Load What You Need

Each extension adds a small amount of startup overhead. Only enable the extensions your application uses. For example, if you're building a static site generator that only needs file I/O:

extension = file.so

Custom Extensions

You can write your own extensions in C. See Writing Extensions for details.

Was this page helpful?