alibaba/nginx-http-concat
FreeA Nginx module for concatenating files in a given context: CSS and JS files usually
FreeFree tier
About alibaba/nginx-http-concat
A dynamic Nginx module for concatenating multiple static files (CSS, JavaScript) into a single HTTP response, reducing the number of requests and improving page load speed. Originally part of Tengine (used by Taobao.com) and inspired by Apache modconcat. Files are combined using URL syntax with double question marks (??) and optional version strings. Configuration directives control MIME types, maximum file count, delimiters, and error handling. Requires compilation into Nginx via module addition.
Key Features
Concatenates multiple files (CSS, JS) into one HTTP response
Configurable MIME types via concat_types directive
Limit on number of concatenated files via concat_max_files (default 10)
Enforce or allow mixed MIME types with concat_unique
Optional delimiter between files via concat_delimiter
Ignore 404/403 errors with concat_ignore_file_error
Supports version strings using third '?' in URL
Part of Tengine Nginx distribution used in production at Taobao
Pros & Cons
Pros
- Reduces number of HTTP requests, improving page load time
- Easy to use URL syntax similar to Apache modconcat
- Highly configurable with multiple directives (types, limits, delimiters)
- Proven in production at Taobao (via Tengine)
- Open source (MIT license) and free
Cons
- Only works with Nginx and requires compilation as a module
- Maximum number of concatenated files limited by OS page size (default 4k URI limit)
- No built-in caching for concatenated responses
- Requires manual setup and configuration in Nginx contexts
Best For
Reducing HTTP requests for CSS and JS assets on high-traffic e-commerce sitesImproving front-end performance by combining static files in NginxSimplifying deployment of concatenated assets without build tools
FAQ
How do I install nginx-http-concat?
Clone the repository from GitHub, add the module to Nginx build configuration using --add-module=path/to/nginx-http-concat, then build and install the Nginx binary.
What is the URL syntax for concatenating files?
Use double question marks (??) to list comma-separated filenames, e.g., http://example.com/??style1.css,style2.css,foo/style3.css. A third ? adds a version string, e.g., ?v=102234.
Can I concatenate CSS and JS files together?
Yes, by setting concat_unique off and adding both MIME types to concat_types. By default, only files of the same MIME type are concatenated.
How do I set the maximum number of files to concatenate?
Use the concat_max_files directive in the Nginx configuration context (http, server, or location). Default is 10.
What if one of the files returns a 404 or 403 error?
Set concat_ignore_file_error on to ignore such errors and continue concatenating the remaining files.