How to customize standard error pages
When setting up a new web server, you may want to display error pages in a pretty way instead of the default one. Also, sometimes error pages should be in the same design as the main site and / or provide users with some additional information, such as, for example, contacts, alternative ways to solve a problem, or something else.
To simplify the process, I created a small utility (direct link to the project in GitHub), essentially a Node.js script that allows you to create static error pages in your own design and with your own text messages. By default, the utility contains only one template in a minimalistic design (with support for accessibility and adaptability, as much as possible in such a simple page). But if you are not satisfied with such a design, then you can easily change it by creating your own: with your own styles, fonts, images and texts.
To be able to create pages in other languages, the utility allows you to use your own language packs that include their own custom text messages.
To simplify integration, the utility automatically creates a web server configuration snippet that can be easily added to your web server configuration. At the moment, the snippet is created only for Nginx. Other types of servers will be added later (alternatively, you can create a Pull Request with such improvements, or issue a Feature Request).
Usage
In a basic use case, all you need to do is clone the project repository to your computer, install the Node.js dependencies, run the build command, copy the result to your server, and update the server configuration.
$ git clone git@github.com:sapachev/error-pages.git
…
$ npm install --production
…
$ npm run build
…
INFO: Start building process
INFO: Flush build directory '/home/error-pages/dist'
INFO: Compile pages from source data:
• /home/error-pages/dist/400.html
• /home/error-pages/dist/401.html
• /home/error-pages/dist/403.html
• /home/error-pages/dist/404.html
• /home/error-pages/dist/410.html
• /home/error-pages/dist/500.html
• /home/error-pages/dist/502.html
• /home/error-pages/dist/503.html
• /home/error-pages/dist/504.html
INFO: Compile web servers config snippets from source data:
• /home/error-pages/dist/nginx-error-pages.conf
INFO: Build Tailwind CSS styles
INFO: Run 'INPUT="/home/error-pages/themes/minimalistic/@assets/css/main.twnd.css" OUTPUT="/home/error-pages/dist/@assets/css/main.css" npm run build:tailwind' command
INFO: Tailwind CSS styles were built
INFO: Copying assets to '/home/error-pages/dist/@assets' directory
INFO: Building process was completed in 1.727sAdvanced usage
In addition to the basic script steps, you can improve compiled pages by changing the parts they are built from: templates, styles, texts, and configuration snippets.
The main configuration of the utility is stored in the file config.json in the root folder, which you can change according to your requirements:
{
"tailwind": true,
"theme": "minimalistic",
"locale": "en"
}Templates
All templates are stored in a folder themeswhere the default theme is minimalistic, which you can change or add a new one. There are no special requirements for page templates: each template is an ordinary HTML document with embedded variables, in place of which there will be texts from localization files. The library is used to handle embedded variables mustache.js. Thus, if you need to implement some special logic in your templates, then you can read the documentation of this library to determine the available templating capabilities.
After adding your template, simply specify it in the configuration file to compile pages using it.
Styles
Template styling is based on the framework Tailwind CSS. With this framework, you can quickly describe page styles without having to write separate CSS code. The entry point for Tailwind styles must be a file themes/<name>/@assets/css/main.twnd.css. A file will be created from it later. main.css, which contains the compiled and minified styles. In addition, you can customize Tailwind by creating a custom configuration located in the file theme.tailwind.config.js in the root of the theme folder, and describe any Tailwind options in it. A complete list of Tailwind options is available at documentation Tailwind himself.
However, if for some reason the use of Tailwind is not required (for example, the styles are already described earlier in CSS), tailwind style compilation can be disabled in the main utility configuration (file config.json). In this case, the styling step will simply be skipped without any impact on the final result.
Text messaging and localization
All text messages are stored in JSON files separated by language and located in the folder src. Each page is created from its corresponding view localization file <Код HTTP>.json (<Код HTTP> is the number corresponding to the HTTP error code). Thus, if you need to create a page for code that is not yet described, then simply create the appropriate JSON file containing the description of this status in the appropriate properties.
Any localization file can be extended with any number of additional properties that you need to display on the page. To define general properties, you can use the file common.json – properties from this file will be applied to each page.
To localize pages, simply create a new folder in the directory src, containing JSON files with page texts. When creating JSON files, you can describe any set of HTTP codes (for example, only for 400 errors) – just follow the naming convention, and do not forget to highlight common texts in the file common.json.
Server Configurations
In the course of work, the Utility will automatically create a snippet for your server, which will contain only those pages that have been created. This snippet will contain the settings for handled errors, and point to the pages that will present them. As stated earlier, only Nginx is currently supported.
To use the received pages, it remains only to copy to the server all the files from the folder dist and enable the use of the snippet in an already existing server configuration. According to the snippet template, all pages should be located in a folder /usr/share/nginx/html/error-pages. If the settings in the snippet do not fit, then you can edit the snippet template in the folder snippets. Just like for themes, configuration templates support mustache.jsthus allowing you to implement any logic in the template (lists, conditions, etc.).
The config itself, I recommend placing it in a folder /etc/nginx/snippets/and to connect it use the configuration line: include /etc/nginx/snippets/nginx-error-pages.conf;. Of course, this is nothing more than a recommendation, because. In reality, things can be different or more complicated.
Below is a simple web server configuration example with a custom error snippet included:
server {
server_name example.com;
access_log /var/log/nginx/example.access.log;
include /etc/nginx/snippets/nginx-error-pages.conf;
location / {
root /data/www;
}
}Demo
You can see what the error pages look like on my website at the following links:
Reporting bugs and feature requests
The utility code cannot be called complicated, however, despite this fact, all significant parts are covered by unit tests. However, this is not a guarantee that there will be no bugs, so if you run into any problems, please report them to me by creating an Issue in the project repository: https://github.com/sapachev/error-pages/issues
You are also welcome to create requests for new features that you would like to see in this utility.
Participation in development
The project is open to everyone, and if you have ideas, and most importantly, the desire and ability to implement them, then I will gladly consider them in the form of a Pull Request. For its part, I am ready to provide you with support in the implementation of your ideas. Feel free to ask me about the code, and possible solutions to your idea.
