Nginx Config Builder

A TypeScript library for building Nginx configuration files programmatically.

Installation

1npm install @dwikyrza/nginx-config-builder

Usage

This library provides two main classes for building Nginx configurations:

NginxConfig

NginxConfig is designed for creating complete Nginx configurations, including HTTP, events, and other top-level directives. Use this when you need to generate a full nginx.conf file.

1import { NginxConfig } from "@dwikyrza/nginx-config-builder";
2
3const config = new NginxConfig();
4
5config.user("nginx");
6config.workerProcesses("auto");
7config.pid("/run/nginx.pid");
8
9config
10  .events()
11  .workerConnections(1024)
12  .multiAccept(true)
13  .useEpoll(true)
14  .acceptMutex(true)
15  .acceptMutexDelay(500);
16
17const http = config.http();
18
19http.applyTypedDirectives({
20  keepalive_timeout: 65,
21  sendfile: true,
22  default_type: "application/octet-stream",
23  tcp_nopush: true,
24  tcp_nodelay: true,
25});
26
27http
28  .clientMaxBodySize("10m")
29  .clientBodyBufferSize("128k")
30  .clientHeaderTimeout(60)
31  .clientBodyTimeout(60)
32  .sendTimeout(60)
33  .gzip(true)
34  .gzipTypes([
35    "text/plain",
36    "text/css",
37    "application/json",
38    "application/javascript",
39    "text/xml",
40    "application/xml",
41  ])
42  .gzipMinLength("1000")
43  .gzipComp(6);
44
45http
46  .addUpstream("backend_servers")
47  .server("127.0.0.1:8001")
48  .server("127.0.0.1:8002")
49  .server("127.0.0.1:8003")
50  .leastConn();
51
52const server = http.addServer(80);
53server.serverName("example.com www.example.com");
54server.accessLog("/var/log/nginx/access.log", "combined");
55server.errorLog("/var/log/nginx/error.log", "warn");
56
57server.listen(443, true);
58server.sslCertificate("/etc/nginx/ssl/example.com.crt");
59server.sslCertificateKey("/etc/nginx/ssl/example.com.key");
60server.sslProtocols("TLSv1.2", "TLSv1.3");
61
62server
63  .addLocation("/")
64  .root("/var/www/html")
65  .index("index.html", "index.htm")
66  .tryFiles("$uri", "$uri/", "/index.html");
67
68server
69  .addLocation("/api")
70  .proxyPass("http://backend_servers")
71  .proxyBuffering(false)
72  .proxySetHeader("X-Real-IP", "$remote_addr")
73  .proxySetHeader("X-Forwarded-For", "$proxy_add_x_forwarded_for")
74  .proxySetHeader("X-Forwarded-Proto", "$scheme")
75  .proxySetHeader("Host", "$host");
76
77server
78  .addLocation("/")
79  .addHeader("X-Frame-Options", "DENY")
80  .addHeader("X-Content-Type-Options", "nosniff")
81  .addHeader("X-XSS-Protection", "1; mode=block")
82  .addHeader("Referrer-Policy", "strict-origin-when-cross-origin");
83
84const output = config.build();
85console.log(output);

Output:

1user nginx;
2
3worker_processes auto;
4
5pid /run/nginx.pid;
6
7events {
8    worker_connections 1024;
9    multi_accept on;
10    use epoll;
11    accept_mutex on;
12    accept_mutex_delay 500ms;
13}
14
15http {
16    sendfile on;
17    keepalive_timeout 65;
18    default_type application/octet-stream;
19    tcp_nopush on;
20    tcp_nodelay on;
21
22    client_max_body_size 10m;
23    client_body_buffer_size 128k;
24    client_header_timeout 60;
25    client_body_timeout 60;
26    send_timeout 60;
27    gzip on;
28    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
29    gzip_min_length 1000;
30    gzip_comp_level 6;
31
32    upstream backend_servers {
33        server 127.0.0.1:8001;
34        server 127.0.0.1:8002;
35        server 127.0.0.1:8003;
36        least_conn;
37    }
38
39    server {
40        listen 80;
41        server_name example.com www.example.com;
42        access_log /var/log/nginx/access.log combined;
43        error_log /var/log/nginx/error.log warn;
44        listen 443 ssl;
45        ssl_certificate /etc/nginx/ssl/example.com.crt;
46        ssl_certificate_key /etc/nginx/ssl/example.com.key;
47        ssl_protocols TLSv1.2 TLSv1.3;
48
49        location  / {
50            root /var/www/html;
51            index index.html index.htm;
52            try_files $uri $uri/ /index.html;
53        }
54
55        location  /api {
56            proxy_pass http://backend_servers;
57            proxy_buffering off;
58            proxy_set_header X-Real-IP $remote_addr;
59            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
60            proxy_set_header X-Forwarded-Proto $scheme;
61            proxy_set_header Host $host;
62        }
63
64        location  / {
65            add_header X-Frame-Options DENY;
66            add_header X-Content-Type-Options nosniff;
67            add_header X-XSS-Protection 1; mode=block;
68            add_header Referrer-Policy strict-origin-when-cross-origin;
69        }
70    }
71}

SiteConfig

SiteConfig is focused on creating individual server configurations. It's ideal for generating site-specific configurations that will be included in the main Nginx configuration. Use this when you want to create configurations for individual sites in /etc/nginx/sites-available/.

1import { SiteConfig } from "@dwikyrza/nginx-config-builder";
2
3const config = new SiteConfig();
4
5const site = config.addServer(80);
6
7site.serverName("example.com");
8site.addLocation("/").root("/var/www/html").index("index.html", "index.htm");
9site
10  .addLocation("/api")
11  .proxyPass("http://localhost:3000")
12  .proxyBuffering(false)
13  .proxySetHeader("X-Real-IP", "$remote_addr")
14  .proxySetHeader("X-Forwarded-For", "$proxy_add_x_forwarded_for")
15  .proxySetHeader("X-Forwarded-Proto", "https");
16
17const output = config.build();
18console.log(output);

Output:

1server {
2    listen 80;
3
4    server_name example.com;
5
6    location / {
7        root /var/www/html;
8        index index.html index.htm;
9    }
10
11    location /api {
12        proxy_pass http://localhost:3000;
13        proxy_buffering off;
14        proxy_set_header X-Real-IP $remote_addr;
15        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16        proxy_set_header X-Forwarded-Proto https;
17    }
18}

Key Differences

• NginxConfig: Creates complete Nginx configurations including:

  • Top-level directives (user, worker_processes, pid)
  • Events block configuration
  • HTTP block with multiple servers
  • Upstream and map configurations
  • Suitable for generating main nginx.conf

• SiteConfig: Focuses on server-level configuration:

  • Single server block configuration
  • No top-level directives or HTTP block
  • Ideal for site-specific configurations
  • Perfect for /etc/nginx/sites-available/ configurations

Examples

For more examples, please refer to the examples folder.

License

This project is licensed under the MIT License - see the LICENSE file for details.