New functionality or Hello, tipi.work application!

There are more than one effective ways to create a new freenginx-based service by:

• utilizing existing functionality
• using third-party modules
• creating a new service with Javascript or Perl modules
• creating a new module on C, C++, or Rust programming languages

This article explains how to create a helloworld application in three different ways:

• with a native directive
• with a Perl module
• with Javascript module

The article details are related to the FreeBSD operating system, its ports tree, packages.

Prerequisites

Latest www/freenginx-devel package is installed, and you have write access to the main directory with configuration files, on FreeBSD that's the /usr/local/etc/freenginx.

Let's install freenginx-devel package:

# pkg update
# pkg install freenginx-devel 

A native way

We're going to create a web service that always replies with 200 HTTP status code and the Hello, tipi.work! as a body of the HTTP:

    location / {
        return 200 "Hello, tipi.work!\n";
    }
    

Add the location block into the main configuration file, /usr/local/etc/freenginx/nginx.conf in the server block, i.e.:

server {
    listen       80;
    server_name  localhost;

    location / {
        return 200 "Hello, tipi.work!\n";
    }
}
    

test and restart freenginx:

# service nginx configtest
# service nginx restart
    

Run a test command:

% curl -i 127.1/
HTTP/1.1 200 OK
Server: freenginx/1.29.4
Date: Tue, 01 Feb 2026 01:55:51 GMT
Content-Type: application/octet-stream
Content-Length: 18
Connection: keep-alive

Hello, tipi.work!

Looks great!

Let's try Perl

Wikipedia says: Perl is a high-level, general-purpose, interpreted, dynamic programming language. Though Perl is not officially an acronym, there are various backronyms in use, including "Practical Extraction and Reporting Language".

The perl module was the first programming language module for nginx, long time before Javascript or Lua modules.

First step

The first step is to enable Perl programming language module functionality for freenginx. So, let's add the load_module directive with the corresponding module on top of the configuration file:

load_module /usr/local/libexec/freenginx/ngx_http_perl_module.so;

Second step

On http level of the freenginx configuration file, we're going to add two more directives, that describes:

• perl_modules -- a directory with the Perl modules
• perl_require -- a Perl module filename

http {

    perl_modules  perl/lib;
    perl_require  tipiwork.pm;

    # other directives...
}

Third step

Let's create another location /perl in the main configuration file, where we pass an action to our perl module:

        location /perl {
             perl tipiwork::hello;
        }

A few words about this action: once a request comes into the /perl, the perl module takes a control and starts an execution of the hello() function.

Forth step

It's time to create a Perl module.

package tipiwork;

use nginx;
use warnings;
use strict;

sub hello {
    my $r = shift;

    my $msg = "Hello, tipi.work! (perl version)\n";
    $r->header_out("Content-Length", length($msg));
    $r->send_http_header();
    $r->print($msg);

    return OK;
}

1;
__END__

Let's run the test.

% curl -i 127.1/perl
HTTP/1.1 200 OK
Server: freenginx/1.29.4
Date: Wed, 04 Feb 2026 15:50:27 GMT
Content-Type: application/octet-stream
Connection: keep-alive
Content-Length: 33

Hello, tipi.work! (perl version)

It looks nice, isn't it?

Let's try Javascript

NGINX Javascript is mature enough, it's a subset of Javascript language, support multiple standards, and good enough in terms of resources consumption.

freenginx configuration file changes

To enable Javascript functionality, add the following line on the top of the /usr/local/etc/freenginx/nginx.conf configuration file.

load_module /usr/local/libexec/freenginx/ngx_http_js_module.so;

Also, it's necessary to load or, in other words, import a file with the code, let's do that on http { } level:

http {

    js_import tipiwork.js;

    # other directives here...
}

And last, but not least, let's create an additional location, on a server level, like it's been done for Perl, with /js name:

        location /js {
             js_content tipiwork.hello;
        }

Javascript code

It's time to write down the code, so here it's the /usr/local/etc/freenginx/tipiwork.js file.

function hello(r) {
    r.return(200, "Hello, tipi.work! (njs version)\n");
}

export default {hello};

It's test time!

% curl -i 127.1/js
HTTP/1.1 200 OK
Server: freenginx/1.29.4
Date: Wed, 04 Feb 2026 16:03:42 GMT
Content-Type: application/octet-stream
Content-Length: 32
Connection: keep-alive

Hello, tipi.work! (njs version)

Great!

Conclusion

There're many ways to extend functionality of freenginx. And this article demonstrated how to create a simple "helloworld" application.