Recently, I needed to add a script to an HTML file using Nginx. Specifically, I wanted to inject an analytics script into the <head> section of a helpdesk software’s HTML. The problem? The software had no built-in way to integrate custom scripts. Since modifying the source code wasn’t an option, I turned to Nginx as a workaround.
Warning
Use this method at your own risk. Modifying HTML responses through Nginx can easily break your webpage if not handled carefully. Always test changes in a controlled environment before deploying them to production.
Nginx is not designed for content manipulation, and this approach should only be used as a last resort. Before proceeding, exhaust all other options, such as modifying the source code, using a built-in integration, or leveraging a client-side solution.
How to Add a Script to HTML Using Nginx
If you need to add a script, or any other HTML to an HTML file using Nginx, you can use the sub_filter module to modify response content on the fly. By leveraging this, we can insert a <script> tag before the closing </head> tag in the HTML document.
Configuration Example
To achieve this, add the following to your Nginx configuration:
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://backend;
proxy_buffering off;
sub_filter '</head>' '<script src="https://example.com/analytics.js"></script></head>';
sub_filter_types text/html;
sub_filter_once on;
}
}Explanation
sub_filter '</head>' '<script src="https://example.com/analytics.js"></script></head>': This replaces</head>with our script tag, ensuring it appears in the document head.sub_filter_types text/html;: Ensures the filter applies only to HTML responses.sub_filter_once on;: Ensures that the replacement happens only once, as</head>should appear only once in a valid HTML document.
Adding an Nginx Proxy for Script Injection
To implement this solution without modifying the existing helpdesk software, I set up another Nginx instance in front of it. This new Nginx proxy handles incoming requests, applies the sub_filter modification, and then forwards the requests to the helpdesk backend.
Here’s how the setup works:
- The client sends a request to
example.com. - Nginx intercepts the request, modifies the HTML response using
sub_filter, and injects the script. - The modified response is then sent to the client, appearing as if it were served directly by the helpdesk software.
This approach keeps the original application untouched while allowing script injection through the proxy layer.
Remarks
- Nginx is primarily a proxy and web server, not a content manipulation tool. Modifying content in this way should be a last resort after exhausting all other options, such as modifying the source code, using a built-in integration, or leveraging a client-side solution. Overuse of
sub_filtercan introduce unexpected behavior, break page functionality, or impact performance. sub_filterrequiresproxy_buffering off;, which may degrade performance, especially for high-throughput sites, by preventing response buffering and increasing load on the backend.- If you’re adding multiple scripts or need flexibility, consider using a tag manager such as Google Tag Manager instead.
- You can use this method to modify or inject any HTML, not just scripts.
Leave a Reply